跳到主要内容

PinInput 验证码输入PinInput

输入固定位数的一次性验证码或 PIN。一格一位，支持整段粘贴和短信自动填充。位数不固定的内容请用 Input。

基本用法

默认 6 位、只收数字。打一位自动跳到下一格，退格回到上一格；在任意一格粘贴整段验证码都会依次填入。

位数、类型与遮罩

尺寸与状态

受控用法

value 是已输入字符连成的字符串。onComplete 在输满的那一下触发，适合直接发起校验。

试试 246810
已输入 0 / 6 位

API

属性

属性类型默认值说明
lengthnumber6位数。
valuestring—当前值（受控）。
defaultValuestring''初始值（非受控）。
onChange(value: string) => void—值变化时触发。
onComplete(value: string) => void—输满时触发。
type'numeric' | 'alphanumeric''numeric'numeric 只收数字并唤起数字键盘；alphanumeric 收字母和数字。
maskboolean—用圆点遮住内容。
size'sm' | 'md''md'尺寸。
disabledboolean—禁用全部格子。
invalidboolean—校验失败。在 Field 里默认跟随 Field。
requiredboolean—必填（每格带 aria-required）。
autoFocusboolean—挂载后聚焦第一格。
namestring—表单字段名：多渲染一个隐藏 input 提交完整的值。
…restHTMLAttributes<HTMLDivElement>—其余属性和 ref 落在外层 role="group" 上。

无障碍

  • 外层是 role="group"，名称取 Field 的标签或 aria-label，都没有时默认叫“验证码”。每一格是独立的文本框，名称是“第 n 位，共 N 位”。
  • ← / → 在格子间移动；Home 到第一格，End 到已输入内容的末尾；Backspace 在空格子里会删掉前一位并退回去。
  • 第一格带 autocomplete="one-time-code"，手机收到短信后可以一键填入；粘贴时自动丢掉不合法的字符。
  • 聚焦某一格会选中其中的字符，直接打字即可覆盖。
  • 错误信息请放在 Field 的 error 里，它会通过 aria-live 播报；不要只靠格子变红。