amis InputVerificationCode 验证码输入组件详解属性、事件与源码实现【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis本篇技术文章以 amis 低代码框架的验证码输入组件input-verification-codeInputVerificationCode为核心完整覆盖其基本用法、密码模式、自定义分隔符、禁用/只读状态等全部官方配置项与事件机制并深入 amis 渲染层packages/amis与 UI 层packages/amis-ui的源码实现帮助你在 JSON Schema 中快速集成多格验证码输入理解其焦点自动迁移、粘贴填充、单字符截断等交互细节背后的触发逻辑。组件定位与注册方式input-verification-code是 amis 表单体系中的一类表单项控件FormItem用于渲染一组并排的独立输入框默认 6 格典型场景包括短信验证码、登录口令、交易密码等。它支持通过粘贴一次性填充多个输入框这是官方文档特别强调的能力。从源码结构看该组件分为两层amis 渲染层InputVerificationCode.tsx 通过FormItem({type: input-verification-code})装饰器注册见该文件 L98-L103负责事件派发dispatchEvent、数据绑定并把 Schema 中的字符串分隔符表达式转译成函数amis-ui 基础组件层VerificationCode.tsx 中的VerificationCodeComponent提供实际的输入框渲染、焦点管理、粘贴处理等交互逻辑。在极简构建中该组件被声明为动态加载注册于 minimal.tsgetComponent: () import(./renderers/Form/InputVerificationCode)而在完整构建中其 Schema 类型在 SchemaFull.ts 中声明为input-verification-code: AMISInputTextSchema。基本用法在表单 Schema 中声明type: input-verification-code并指定name即可得到默认 6 格的验证码输入。以下示例继承自官方文档{ type: form, api: /api/mock2/form/saveForm, debug: true, body: [ { type: input-verification-code, name: verificationCode } ] }不指定length时源码中defaultLength 6VerificationCode.tsx即渲染 6 个输入框每格只接受一个字符输入框之间的间距、边框、聚焦态均由 CSS 变量控制后文样式小节详述。密码模式指定masked true可开启密码模式所有输入框将以typepassword渲染字符显示为掩码适合输入敏感口令。{ type: form, api: /api/mock2/form/saveForm, debug: true, body: [ { type: input-verification-code, name: verificationCode, masked: true } ] }在 VerificationCode.tsx 中可以看到masked直接决定输入框类型type{masked ? password : text}需要注意密码模式下输入框宽度依然固定掩码点的大小由浏览器决定实际效果建议以真机预览为准。自定义分隔符指定separator可以自定义每个输入框之后渲染的分隔符。该属性支持 amis 表达式且表达式中只可以访问两个变量index当前分隔符所在位置即它位于第几个输入框之后从 0 开始character该输入框当前填写的字符。官方文档给出的示例为 9 位验证码用表达式在特定位置插入-{ type: form, api: /api/mock2/form/saveForm, debug: true, body: [ { type: input-verification-code, name: verificationCode, length: 9, separator: ${((index 1) % 3 || index 7) ? null : -} } ] }分隔符表达式的实现链路值得注意amis 渲染层在 InputVerificationCode.tsx 的render()中若separator是字符串就将其包装为(data: {index, character}) resolveVariableAndFilter(separator, data)即通过 amis 的模板解析引擎求值若表达式结果为空如null该位置不渲染任何内容求值后的函数在 UI 层被逐个输入框调用VerificationCode.tsx 中{separator?.({index, character: v!})}v即该格当前的字符值。因此分隔符可以做静态文本如-也可以根据填写内容动态变化如未填写时渲染占位提示。状态控制禁用与只读指定disabled true可开启禁用模式输入框整体不可交互并叠加is-disabled类名呈现禁用样式指定readOnly true可开启只读模式此时源码中会直接摘除onClick、onPaste、onKeyDown、onChange等交互回调VerificationCode.tsx 中均以!readOnly ? handler : undefined条件挂载只保留值展示。{ type: form, api: /api/mock2/form/saveForm, debug: true, body: [ { type: input-verification-code, name: verificationCodeDisabled, value: 123456, disabled: true }, { type: input-verification-code, name: verificationCodeReadOnly, value: 987654, readOnly: true } ] }属性表当做表单项使用时除了支持 普通表单项属性表 中的配置以外还支持以下专属配置属性名类型默认值说明lengthnumber6验证码的长度根据长度渲染对应个数的输入框maskedbooleanfalse是否是密码模式separatorstring-分隔符支持表达式表达式只可以访问index、character变量参考自定义分隔符示例结合 InputVerificationCode.tsx 中定义的VerificationCodeSchema接口还可直接使用value初始值/回填值、disabled、readOnly等属性length的容错逻辑在 useVerificationCode 中实现当length非法非正数时回退到默认值 6。事件表当前组件会对外派发以下事件可以通过onEvent来监听事件名称事件参数说明finish-输入框都被填充后触发的回调change-输入值改变时触发的回调finish全部填充完成所有输入框被填满当前值长度等于length时触发。可以尝试通过${event.data.value}获取填写的数据{ type: input-verification-code, onEvent: { finish: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.data.value} } } ] } } }change输入值改变每次有效输入含粘贴、退格导致值变化时触发同样可通过${event.data.value}获取当前值{ type: input-verification-code, onEvent: { change: { actions: [ { actionType: toast, args: { msgType: info, msg: ${event.data.value} } } ] } } }从 InputVerificationCode.tsx 的源码可以看到两个事件的派发细节onFinish通过dispatchEvent(finish, {...data, value}, this)派发事件参数中除表单作用域数据外额外携带value字段onChange先派发change事件若监听者未阻止该事件rendererEvent?.prevented为假才调用onChange?.(value)把值同步到表单数据。也就是说onEvent中可以通过preventDefault类机制拦截值更新——这是 amis 事件体系的标准行为。源码实现交互行为是怎么来的amis-ui 的 useVerificationCode Hook 封装了全部核心交互可以据此准确预判组件行为1. 每格单字符。onChange处理函数中char.replace(indexVal, ).split().pop() || L231-L237意味着每格只保留新输入内容中的最后一个字符多字符输入会自动截断。2. 自动焦点迁移。每次filledValue变化后useEffect会调用focusFirstEmptyInput()L152-L175只要当前焦点在验证码输入框组内就自动把焦点移到第一个空格当所有格填满时还会主动让最后一个输入框blur()失焦避免焦点残留在已完成的输入组上。3. 粘贴填充。handlePasteL189-L198拦截粘贴事件取剪贴板文本按字符拆分从当前格开始向后填充filledValue.slice(0, index).concat(text.split()).join()。这解释了官方文档开头强调的可通过粘贴完成填充数据——粘贴 6 位数字即可一次性填满 6 格。4. 退格逻辑。onKeyDown中L215-L229若后一格仍有值则阻止退格先把后一格清空退格前会做边界修正空格退格时回退到上一格保证删除顺序符合直觉。5. 触发时机。tryUpdateValueL177-L187中值变化时先调用props.onChange随后当newVal.length length时调用props.onFinish——即finish是恰好填满的一次性触发点change则是每一次有效变更的触发点。6. 受控/非受控合并。Hook 通过useMergeValueL104-L132合并外部value与内部状态外部传入value时以外部为准受控未传入时内部状态自持非受控这解释了状态示例中直接用value: 123456回填静态值即可生效的原因。样式与主题定制组件整体布局由 _verificationCode.scss 定义容器为display: flex单格输入框宽px2rem(35px)适配移动端 rem 缩放列间距 4px边框、圆角、内边距、字号、聚焦阴影、禁用态背景等全部取自--Form-input-*CSS 变量如--Form-input-borderColor、--Form-input-onFocused-borderColor、--Form-input-onDisabled-bg。这意味着你可以按 amis 的主题体系统一定制验证码输入框外观——覆盖对应的--Form-input-*变量即可改变其边框、聚焦与禁用样式而无需为验证码组件单独写样式禁用态通过is-disabled类名切换光标与背景。小结input-verification-code是 amis 表单中面向验证码场景的专用控件length控制格数默认 6、masked切换密码掩码、separator以表达式实现位置级动态分隔符、disabled/readOnly控制状态事件侧以finish填满与change变更构成完整的反馈闭环。配合 amis 通用的onEvent与name数据绑定机制可以在纯 JSON Schema 中完成从验证码采集到提交的全流程无需手写任何 React 代码。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考