PinInput

PIN 码输入框,支持数字/字母模式。包含 PinInputRoot(容器)与 PinInputInput(单格)。

Anatomy

• PinInputRoot输入容器,管理整体 modelValue 与 complete 事件
  • PinInputInput单个输入格,通过 index 指定位置

基本用法

6 位数字 PIN

使用 v-model 绑定字符串数组,输入满时触发 complete。

<script setup lang="ts">
import { PinInputInput, PinInputRoot } from '@tripo3d/design';
import { ref } from 'vue';

const value = ref<string[]>([]);

function handleComplete(val: string[]) {
  console.log(val);
}
</script>

<template>
  <PinInputRoot
    v-model="value"
    type="numeric"
    class="flex gap-2"
    @complete="handleComplete"
  >
    <PinInputInput
      v-for="i in 6"
      :key="i"
      :index="i - 1"
      class="w-10 h-10"
    />
  </PinInputRoot>
</template>

掩码模式

mask

开启掩码后,输入内容以占位符显示,适合密码场景。

<PinInputRoot type="numeric" mask>
  <PinInputInput v-for="i in 4" :key="i" :index="i - 1" />
</PinInputRoot>

字母模式

type='alphabetic'

允许输入字母,适合邀请码等场景。

<PinInputRoot type="alphabetic">
  <PinInputInput v-for="i in 5" :key="i" :index="i - 1" />
</PinInputRoot>

API

PinInputRoot Props

名称	类型	默认值	说明
modelValue	string[]	—	受控值,每格一个字符
type	'numeric' | 'alphabetic'	'numeric'	允许输入的字符类型
mask	boolean	—	是否以占位符显示(密码模式)
disabled	boolean	—	禁用整个输入组
otp	boolean	—	启用浏览器 OTP 自动填充提示
class	string	—	容器 class

其余 props 透传至 reka-ui PinInputRoot,详见 reka-ui 文档。

PinInputRoot Events

事件	Payload	说明
update:modelValue	(value: string[])	输入值变化
complete	(value: string[])	所有格子均填满时触发

PinInputInput Props

名称	类型	默认值	说明
index	number	—	必填。当前格子的位置索引,从 0 开始
class	string	—	单格 class

可访问性

• 基于 reka-ui PinInput,支持键盘方向键在各格之间移动焦点
• 粘贴剪贴板内容时自动拆分填入各格
• 建议通过 otp 属性启用 autocomplete="one-time-code",辅助验证码自动填充
• 为整个输入组外围提供 <Label> 或 aria-label 说明用途