radix-vue PinInputInput 深度指南从 Props 到源码级交互实现【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue本指南以 radix-vueReka UI中 PinInput 组件族的输入单元PinInputInput为对象围绕其组件元数据文档 docs/content/meta/PinInputInput.md 展开。你将掌握 PinInputInput 的完整 Props 语义index、as、asChild、disabled、它与 PinInputRoot 的上下文协作方式以及源码中实现的自动聚焦、多字符分发、粘贴过滤、方向键导航、IME 组合输入与 OTP 焦点管理机制最终能够基于真实源码写出健壮的验证码 / PIN 码输入组件。PinInputInput 在组件体系中的定位PinInputPIN 输入组件族由两个部分构成PinInputRoot 负责整体状态modelValue、placeholder、mask、otp、type、dir、disabled、complete事件并通过 Vue 的provide/inject建立上下文PinInputInput则是渲染单个输入框的单元组件一个 PIN 输入控件通常由多个 PinInputInput 实例组成。从源码结构看两者存在明确的分工关系PinInputRoot.vue 在providePinInputRootContext中把modelValue、placeholder、mask、otp、type、dir、disabled、isCompleted、inputElements集合等注入上下文PinInputInput.vue 通过injectPinInputRootContext()消费这些状态负责完成单格输入、光标跳转、删除回溯、粘贴分配、无障碍标注等全部细粒度交互。因此理解 PinInputInput 是理解整个 PIN 输入组件的钥匙它承载了几乎所有“输入体验”层面的逻辑。Props 完整解析PinInputInput 的 Props 定义在 PinInputInput.vue接口PinInputInputProps extends PrimitiveProps通过packages/core/src/PinInput/index.ts对外导出类型。全部 Props 如下表NameDescriptionTypeRequiredDefaultasThe element or component this component should render as. Can be overwritten by asChild.AsTag \| ComponentNoinputasChildChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.booleanNo-disabledWhen true, prevents the user from interacting with the pin inputbooleanNo-indexPosition of the value this input binds to.numberYes-index唯一必填属性决定值的绑定位置index是 PinInputInput 与 PinInputRoot 状态模型之间的“坐标”。它声明了当前输入框对应modelValue数组中的哪一个位置渲染层PinInputInput.vue 通过context.currentModelValue.value[props.index]计算currentValue并将其绑定到Primitive的:value上写入层updateModelValueAt(props.index, value)PinInputInput.vue会复制当前模型数组、更新指定下标再整体回写context.modelValue.value。在数字模式下updateModelValueAt还会做类型转换空字符串或非法数字写为undefined合法数字写为number而文本模式直接存字符串。这解释了为什么PinInputValuenumber类型是(number | undefined)[]见 PinInputRoot.vue——清空的格子会留下undefined空洞测试用例中也验证了这一点见下文“测试验证”。典型用法是在v-for中为每个 PinInputInput 传入递增的indexscript setup langts import { ref } from vue import { PinInputInput, PinInputRoot } from radix-vue const value refstring[]([]) /script template PinInputRoot v-modelvalue placeholder* PinInputInput v-for(_, index) in 5 :keyindex :indexindex / /PinInputRoot /templateas与asChildPrimitive 组合能力PinInputInput 继承自 radix-vue 的 Primitive 体系因此具备与所有 radix-vue 组件一致的渲染控制能力as的默认值为inputPinInputInput.vue 中withDefaults指定可以替换为任意 HTML 标签或组件asChild为true时将直接以插槽中的单个子元素作为渲染目标并把本组件的 props 与行为合并到该子元素上。模板中组件通过Primitive完成实际渲染PinInputInput.vue并基于上下文自动附加一系列原生属性typemask模式下为password否则为textinputmode数字模式下为numeric否则为textpattern数字模式下为[0-9]*便于移动端唤起数字键盘autocompleteOTP 模式下为one-time-code否则为falseautocapitalizenone避免移动端首字母大写干扰验证码输入。这些属性让单格输入框天然具备移动端友好性无需开发者手工配置。disabled组件级禁用与根级禁用的合并disabled是组件级独立开关但实际生效值是组件级与根级取“或”的结果const disabled computed(() props.disabled || context.disabled.value)PinInputInput.vue也就是说只要 PinInputRoot 设置了disabled所有单格输入框都会禁用单独给某个 PinInputInput 设置disabled也能局部禁用。禁用状态会同步为原生disabled属性并输出data-disabled数据属性。上下文注入的行为由 Root 控制、Input 执行PinInputInput 的大部分表现由 Root 注入的上下文驱动这些配置并不直接写在 PinInputInput 的 Props 上但理解它们才能正确使用本组件Root 配置项对 PinInputInput 行为的影响源码依据placeholder空输入框的占位字符如*聚焦的空格会临时隐藏占位符PinInputInput.vuemask单格以password类型渲染隐藏已输入内容模板:type绑定otp启用一次性密码语义autocompleteone-time-code并强制从第一个空格开始填充、箭头键不可越过空格PinInputInput.vuetypenumber过滤非数字输入、粘贴时剔除字母、inputmodenumericNUMBER_REG/NON_NUMBER_REG与handleInput/handlePastedir方向键导航遵循rtl/ltr阅读方向handleKeydown中dir: context.dir.valueRoot 还在 PinInputRoot.vue 渲染了一个VisuallyHiddenInput视觉隐藏输入框承载name、required等表单语义并把currentModelValue.join()作为提交值确保 PIN 输入在无 JS 表单提交与无障碍场景下也可用。源码级交互实现PinInputInput 的输入体验从何而来单字符输入与自动前进handleInputPinInputInput.vue是核心入口每次输入一个字符后写入当前下标对应的模型位置并立即把焦点交给index 1的下一个输入框。数字模式下还会先用NUMBER_REG校验、再用NON_NUMBER_REG剔除非法字符保证只保留数字。多字符分发粘贴、密码管理器自动填充与 IME 提交当一次事件携带多个字符粘贴、密码管理器自动填充、IME 组合输入提交时handleMultipleCharacterPinInputInput.vue会把字符串按顺序逐字分发到连续多个输入框中并且如果字符串长度大于等于输入框总数从第 0 格开始填否则从当前index开始填数字模式下逐字parseInt并跳过非数字字符填完所有格子后焦点落在最后一个被填充格子的下一格。handlePastePinInputInput.vue在数字模式下还会先整体剔除剪贴板中的非数字字符实现“粘贴a1b2c3得到1 2 3”的效果。退格 / Delete 的智能回溯handleBackspacePinInputInput.vue实现了验证码输入的标准体验当前格有值时清空当前格当前格为空时焦点退回上一格并清空上一格的值。handleDeletePinInputInput.vue则只清空当前格不移焦。方向键导航与 OTP 模式约束handleKeydownPinInputInput.vue借助共享工具useArrowNavigation实现left / right / up / down / home / end键在输入框之间移动。特别地OTP 模式下会先通过getFirstEmptyInputIndex找到第一个空位把可导航范围裁剪到“第一个空格为止”从而禁止方向键越过中间的空格符合“OTP 必须从左到右按序填写”的预期。IME 组合输入保护对于中文、日文等使用输入法IME的场景PinInputInput.vue 通过useComposing处理compositionstart/compositionend组合期间不移动焦点、不写入模型组合提交时若得到多字符结果则走handleMultipleCharacter分发。handleInput与handleKeydown中也都对isComposing做了短路判断避免候选框导航与箭头键冲突。OTP 模式下的焦点重定向OTP 模式下getEarlierEmptyInputPinInputInput.vue会找出当前格之前是否存在空位若存在handleMousedown与handleFocusPinInputInput.vue会把点击 / 外部聚焦重定向到第一个空格。同时handleFocus会设置setSelectionRange(1, 1)将光标置于末尾并在聚焦的空格上临时隐藏占位符。值得注意的细节是来自兄弟输入框的聚焦如Tab键顺序导航不会被重定向避免键盘用户被困在输入组内源码注释提及 issue #2943。无障碍与数据属性每个 PinInputInput 会自动生成aria-label形如pin input 1 of 5根据index与输入框总数动态计算PinInputInput.vuedata-completeRoot 判定所有格子已填满isCompleted时输出PinInputRoot.vuedata-disabled禁用时输出。配合 Root 的complete事件所有格子填满后触发见 PinInputRoot.vue可以无缝接入表单校验与业务回调PinInputRoot v-modelvalue completecode onVerify(code.join()) PinInputInput v-for(_, index) in 5 :keyindex :indexindex / /PinInputRoot测试验证行为即契约PinInput.test.ts 是上述行为的可执行契约值得逐条对照占位符行为聚焦的空格不显示占位符失焦 / 填值后恢复render placeholder用例组逐字输入与自动前进键入test后五个格子依次为[t,e,s,t,]焦点停在最后粘贴分发在第 2 格粘贴test会从第 2 格开始依次填充after user paste test at 2nd input退格回溯满格后按 Backspace 依次清空并回退Delete 只清当前格数字模式过滤键入或粘贴test结果全部为空粘贴a1b2c3d4e5只保留数字并触发completecomplete事件填满后事件载荷为完整数组如[a,p,p,l,e]OTP 焦点管理外部点击第 3 格会被重定向到第 1 个空格箭头键不能越过空格Tab/ShiftTab仍可顺序导航而不被困住IME 组合组合期间不移焦、提交后才处理数字模式下拒绝非数字的 IME 提交多字符组合提交按位分发。此外两组测试均通过了axe无障碍扫描should pass axe accessibility tests可以作为无障碍回归的参考基线。小结PinInputInput 是一个“职责高度内聚”的原子组件对外只暴露index、disabled、as、asChild四个 Props其余全部行为由 Root 上下文驱动并在内部消化了验证码输入中几乎所有的边缘交互——多字符分发、数字过滤、退格回溯、方向键约束、IME 保护与 OTP 焦点重定向。阅读其源码时建议从 PinInputInput.vue 的事件处理链handleInput→handleMultipleCharacter→updateModelValueAt切入再对照 PinInput.test.ts 中的用例逐条验证即可完整建立对该组件的认知。【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 radix-vue PinInputInput 深度指南：从 Props 到源码级交互实现
radix-vue PinInputInput 深度指南从 Props 到源码级交互实现【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue本指南以 radix-vueReka UI中 PinInput 组件族的输入单元PinInputInput为对象围绕其组件元数据文档 docs/content/meta/PinInputInput.md 展开。你将掌握 PinInputInput 的完整 Props 语义index、as、asChild、disabled、它与 PinInputRoot 的上下文协作方式以及源码中实现的自动聚焦、多字符分发、粘贴过滤、方向键导航、IME 组合输入与 OTP 焦点管理机制最终能够基于真实源码写出健壮的验证码 / PIN 码输入组件。PinInputInput 在组件体系中的定位PinInputPIN 输入组件族由两个部分构成PinInputRoot 负责整体状态modelValue、placeholder、mask、otp、type、dir、disabled、complete事件并通过 Vue 的provide/inject建立上下文PinInputInput则是渲染单个输入框的单元组件一个 PIN 输入控件通常由多个 PinInputInput 实例组成。从源码结构看两者存在明确的分工关系PinInputRoot.vue 在providePinInputRootContext中把modelValue、placeholder、mask、otp、type、dir、disabled、isCompleted、inputElements集合等注入上下文PinInputInput.vue 通过injectPinInputRootContext()消费这些状态负责完成单格输入、光标跳转、删除回溯、粘贴分配、无障碍标注等全部细粒度交互。因此理解 PinInputInput 是理解整个 PIN 输入组件的钥匙它承载了几乎所有“输入体验”层面的逻辑。Props 完整解析PinInputInput 的 Props 定义在 PinInputInput.vue接口PinInputInputProps extends PrimitiveProps通过packages/core/src/PinInput/index.ts对外导出类型。全部 Props 如下表NameDescriptionTypeRequiredDefaultasThe element or component this component should render as. Can be overwritten by asChild.AsTag \| ComponentNoinputasChildChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.booleanNo-disabledWhen true, prevents the user from interacting with the pin inputbooleanNo-indexPosition of the value this input binds to.numberYes-index唯一必填属性决定值的绑定位置index是 PinInputInput 与 PinInputRoot 状态模型之间的“坐标”。它声明了当前输入框对应modelValue数组中的哪一个位置渲染层PinInputInput.vue 通过context.currentModelValue.value[props.index]计算currentValue并将其绑定到Primitive的:value上写入层updateModelValueAt(props.index, value)PinInputInput.vue会复制当前模型数组、更新指定下标再整体回写context.modelValue.value。在数字模式下updateModelValueAt还会做类型转换空字符串或非法数字写为undefined合法数字写为number而文本模式直接存字符串。这解释了为什么PinInputValuenumber类型是(number | undefined)[]见 PinInputRoot.vue——清空的格子会留下undefined空洞测试用例中也验证了这一点见下文“测试验证”。典型用法是在v-for中为每个 PinInputInput 传入递增的indexscript setup langts import { ref } from vue import { PinInputInput, PinInputRoot } from radix-vue const value refstring[]([]) /script template PinInputRoot v-modelvalue placeholder* PinInputInput v-for(_, index) in 5 :keyindex :indexindex / /PinInputRoot /templateas与asChildPrimitive 组合能力PinInputInput 继承自 radix-vue 的 Primitive 体系因此具备与所有 radix-vue 组件一致的渲染控制能力as的默认值为inputPinInputInput.vue 中withDefaults指定可以替换为任意 HTML 标签或组件asChild为true时将直接以插槽中的单个子元素作为渲染目标并把本组件的 props 与行为合并到该子元素上。模板中组件通过Primitive完成实际渲染PinInputInput.vue并基于上下文自动附加一系列原生属性typemask模式下为password否则为textinputmode数字模式下为numeric否则为textpattern数字模式下为[0-9]*便于移动端唤起数字键盘autocompleteOTP 模式下为one-time-code否则为falseautocapitalizenone避免移动端首字母大写干扰验证码输入。这些属性让单格输入框天然具备移动端友好性无需开发者手工配置。disabled组件级禁用与根级禁用的合并disabled是组件级独立开关但实际生效值是组件级与根级取“或”的结果const disabled computed(() props.disabled || context.disabled.value)PinInputInput.vue也就是说只要 PinInputRoot 设置了disabled所有单格输入框都会禁用单独给某个 PinInputInput 设置disabled也能局部禁用。禁用状态会同步为原生disabled属性并输出data-disabled数据属性。上下文注入的行为由 Root 控制、Input 执行PinInputInput 的大部分表现由 Root 注入的上下文驱动这些配置并不直接写在 PinInputInput 的 Props 上但理解它们才能正确使用本组件Root 配置项对 PinInputInput 行为的影响源码依据placeholder空输入框的占位字符如*聚焦的空格会临时隐藏占位符PinInputInput.vuemask单格以password类型渲染隐藏已输入内容模板:type绑定otp启用一次性密码语义autocompleteone-time-code并强制从第一个空格开始填充、箭头键不可越过空格PinInputInput.vuetypenumber过滤非数字输入、粘贴时剔除字母、inputmodenumericNUMBER_REG/NON_NUMBER_REG与handleInput/handlePastedir方向键导航遵循rtl/ltr阅读方向handleKeydown中dir: context.dir.valueRoot 还在 PinInputRoot.vue 渲染了一个VisuallyHiddenInput视觉隐藏输入框承载name、required等表单语义并把currentModelValue.join()作为提交值确保 PIN 输入在无 JS 表单提交与无障碍场景下也可用。源码级交互实现PinInputInput 的输入体验从何而来单字符输入与自动前进handleInputPinInputInput.vue是核心入口每次输入一个字符后写入当前下标对应的模型位置并立即把焦点交给index 1的下一个输入框。数字模式下还会先用NUMBER_REG校验、再用NON_NUMBER_REG剔除非法字符保证只保留数字。多字符分发粘贴、密码管理器自动填充与 IME 提交当一次事件携带多个字符粘贴、密码管理器自动填充、IME 组合输入提交时handleMultipleCharacterPinInputInput.vue会把字符串按顺序逐字分发到连续多个输入框中并且如果字符串长度大于等于输入框总数从第 0 格开始填否则从当前index开始填数字模式下逐字parseInt并跳过非数字字符填完所有格子后焦点落在最后一个被填充格子的下一格。handlePastePinInputInput.vue在数字模式下还会先整体剔除剪贴板中的非数字字符实现“粘贴a1b2c3得到1 2 3”的效果。退格 / Delete 的智能回溯handleBackspacePinInputInput.vue实现了验证码输入的标准体验当前格有值时清空当前格当前格为空时焦点退回上一格并清空上一格的值。handleDeletePinInputInput.vue则只清空当前格不移焦。方向键导航与 OTP 模式约束handleKeydownPinInputInput.vue借助共享工具useArrowNavigation实现left / right / up / down / home / end键在输入框之间移动。特别地OTP 模式下会先通过getFirstEmptyInputIndex找到第一个空位把可导航范围裁剪到“第一个空格为止”从而禁止方向键越过中间的空格符合“OTP 必须从左到右按序填写”的预期。IME 组合输入保护对于中文、日文等使用输入法IME的场景PinInputInput.vue 通过useComposing处理compositionstart/compositionend组合期间不移动焦点、不写入模型组合提交时若得到多字符结果则走handleMultipleCharacter分发。handleInput与handleKeydown中也都对isComposing做了短路判断避免候选框导航与箭头键冲突。OTP 模式下的焦点重定向OTP 模式下getEarlierEmptyInputPinInputInput.vue会找出当前格之前是否存在空位若存在handleMousedown与handleFocusPinInputInput.vue会把点击 / 外部聚焦重定向到第一个空格。同时handleFocus会设置setSelectionRange(1, 1)将光标置于末尾并在聚焦的空格上临时隐藏占位符。值得注意的细节是来自兄弟输入框的聚焦如Tab键顺序导航不会被重定向避免键盘用户被困在输入组内源码注释提及 issue #2943。无障碍与数据属性每个 PinInputInput 会自动生成aria-label形如pin input 1 of 5根据index与输入框总数动态计算PinInputInput.vuedata-completeRoot 判定所有格子已填满isCompleted时输出PinInputRoot.vuedata-disabled禁用时输出。配合 Root 的complete事件所有格子填满后触发见 PinInputRoot.vue可以无缝接入表单校验与业务回调PinInputRoot v-modelvalue completecode onVerify(code.join()) PinInputInput v-for(_, index) in 5 :keyindex :indexindex / /PinInputRoot测试验证行为即契约PinInput.test.ts 是上述行为的可执行契约值得逐条对照占位符行为聚焦的空格不显示占位符失焦 / 填值后恢复render placeholder用例组逐字输入与自动前进键入test后五个格子依次为[t,e,s,t,]焦点停在最后粘贴分发在第 2 格粘贴test会从第 2 格开始依次填充after user paste test at 2nd input退格回溯满格后按 Backspace 依次清空并回退Delete 只清当前格数字模式过滤键入或粘贴test结果全部为空粘贴a1b2c3d4e5只保留数字并触发completecomplete事件填满后事件载荷为完整数组如[a,p,p,l,e]OTP 焦点管理外部点击第 3 格会被重定向到第 1 个空格箭头键不能越过空格Tab/ShiftTab仍可顺序导航而不被困住IME 组合组合期间不移焦、提交后才处理数字模式下拒绝非数字的 IME 提交多字符组合提交按位分发。此外两组测试均通过了axe无障碍扫描should pass axe accessibility tests可以作为无障碍回归的参考基线。小结PinInputInput 是一个“职责高度内聚”的原子组件对外只暴露index、disabled、as、asChild四个 Props其余全部行为由 Root 上下文驱动并在内部消化了验证码输入中几乎所有的边缘交互——多字符分发、数字过滤、退格回溯、方向键约束、IME 保护与 OTP 焦点重定向。阅读其源码时建议从 PinInputInput.vue 的事件处理链handleInput→handleMultipleCharacter→updateModelValueAt切入再对照 PinInput.test.ts 中的用例逐条验证即可完整建立对该组件的认知。【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考