OTPInput 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。

组件介绍

提供 4–8 位数字一次性验证码输入，支持整码粘贴、短信自动填充、原生表单提交与重置。

使用选择

用于输入已经由业务或身份服务发送的一次性数字验证码。组件只负责输入，不负责发送短信、倒计时或验证验证码。

• 默认 6 位，可选 4、5、6、7、8 位；普通输入会过滤非数字并限制长度；粘贴严格校验，规则见下文。

• oncomplete 仅在用户输入产生一个新的完整值时触发；初始化、外部赋值和相同完整值重复同步不触发。

• name、form、required、disabled、readonly 与 autocomplete="one-time-code" 均落到真实 input。

快速开始

<script lang="ts">    import { OTPInput } from "@snowui-design-system/components";    let code = $state("");</script> <OTPInput bind:value={code} aria-label="Verification code" oncomplete={(value) => console.log(value)} />

API

公开样式覆盖：--snowui-otp-input-gap-override、--snowui-otp-input-size-override、--snowui-otp-input-radius-override、--snowui-otp-input-font-size-override、--snowui-otp-input-line-height-override。

使用边界与详细说明

• 单一真实 <input type="text" inputmode="numeric"> 负责键盘、选择、删除、替换、自动填充、表单和辅助技术；根 role="group" 与 input 共享显式可访问名称，分格为 aria-hidden 视觉层。错误通过 aria-describedby 关联，并由 polite 状态区播报。

• 点击任意格会选择对应字符，因此下一次键入替换该格；活动格跟随 input 的真实 selection。原生方向键、Home、End、Backspace、Delete、选择替换与撤销行为保持可用。

• 普通输入只保留 ASCII 数字 0–9，自动激活右侧下一格；点击或方向键不能跳到第一未填格之后。已填格可点击选择并替换。

• 粘贴先检查全部内容，空白、分隔符、字母、全角数字等均视为非数字，不做静默过滤。

• 粘贴长度恰好等于 length 时，无论当前激活位置都从首格完整覆盖。

• 在后续格（index > 0）粘贴，只要已有连续前缀且不超过右侧剩余格数，就从当前格补入；允许未填满。例如 4 位码已有 12，第三格粘贴 34 得到 1234，粘贴 3 得到 123。

• 在首格粘贴不足/超长数字时清空全部内容并报错；在后续格粘贴超出剩余格数，或粘贴非数字时，拒绝整次粘贴并保留原值。

• 内置粘贴错误使用 Input 同款边框、聚焦环、shake 和错误文字，持续 2 秒后恢复；再次无效粘贴重新计时。reset、卸载清理 timer；错误期间不锁定输入。外部 invalid 仍由调用方负责。

• 激活框通过 TAB_INDICATOR_MOTION 平移，数字出现/替换通过 NUMBER_POP_APPEAR_MOTION；reduced-motion 保持值、语义和焦点，直接呈现最终位置。

• 调用方必须提供 aria-label、aria-labelledby 或关联 <label>。disabled 不提交，readonly 仍提交。

• form reset 默认恢复 defaultValue，未提供时恢复首次 value；取消的 reset 保留当前值。监听按当前 input.form 判定，因此 form 改变后自动关联新表单。reset 的零延迟收尾 timer 在重复 reset 或卸载时清理。