分格输入 pin-input

数据录入组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

每格都是原生输入框，敲一个字符自动跳下一格；粘贴整串会从落点那一格起按格铺开

验证码

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhPinInputRoot :length="4" placeholder="·">
    <XhPinInputLabel>验证码</XhPinInputLabel>
    <!-- 格间距长在格子自己身上，这层包裹只负责排成一行、不要再加 gap -->
    <div style="display: flex">
      <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
    </div>
  </XhPinInputRoot>
</template>

一次性验证码

otp 补上 autocomplete=one-time-code，隐藏输入把拼好的整串交给表单，填满那一刻发 value-complete

短信验证码

填满时拿到：（未填满）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhPinInputHiddenInput,
  XhPinInputInput,
  XhPinInputLabel,
  XhPinInputRoot,
} from "@xihan-ui/vue";

const code = ref<string[]>([]);
const submitted = ref("");
</script>

<template>
  <XhPinInputRoot
    v-model:value="code"
    :length="6"
    name="code"
    placeholder="·"
    otp
    @value-complete="submitted = $event.valueAsString"
  >
    <XhPinInputLabel>短信验证码</XhPinInputLabel>
    <div style="display: flex">
      <XhPinInputInput v-for="i in 6" :key="i" :index="i - 1" />
    </div>
    <XhPinInputHiddenInput />
  </XhPinInputRoot>
  <span>填满时拿到：{{ submitted || "（未填满）" }}</span>
</template>

遮蔽与字符类别

mask 把每格转成密码框，type 决定哪类字符进得来，其余按键既不进值也不留在框里

支付密码（遮蔽）

兑换码（数字与字母）

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhPinInputRoot :length="4" mask>
    <XhPinInputLabel>支付密码（遮蔽）</XhPinInputLabel>
    <div style="display: flex">
      <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
    </div>
  </XhPinInputRoot>

  <XhPinInputRoot :length="4" type="alphanumeric">
    <XhPinInputLabel>兑换码（数字与字母）</XhPinInputLabel>
    <div style="display: flex">
      <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
    </div>
  </XhPinInputRoot>
</template>

禁用与校验失败

disabled 让每格都带原生 disabled 且不参与提交，invalid 只做标注、照样能改

禁用

校验失败

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhPinInputRoot :length="4" :default-value="['1', '2', '3', '4']" disabled>
    <XhPinInputLabel>禁用</XhPinInputLabel>
    <div style="display: flex">
      <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
    </div>
  </XhPinInputRoot>

  <XhPinInputRoot :length="4" :default-value="['1', '2', '3', '4']" invalid>
    <XhPinInputLabel>校验失败</XhPinInputLabel>
    <div style="display: flex">
      <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
    </div>
  </XhPinInputRoot>
</template>

形态

variant 只改每格的颜色槽位，跳格与粘贴铺开的行为三档一致

outline

subtle

ghost

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";

const variants = ["outline", "subtle", "ghost"] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 20px">
    <XhPinInputRoot v-for="v in variants" :key="v" :variant="v" :length="4" placeholder="·">
      <XhPinInputLabel>{{ v }}</XhPinInputLabel>
      <!-- 格间距长在格子自己身上，这层包裹只负责排成一行 -->
      <div style="display: flex">
        <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
      </div>
    </XhPinInputRoot>
  </div>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 outline 只看语气的差别

brand

neutral

success

warning

danger

info

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 20px">
    <XhPinInputRoot
      v-for="t in tones"
      :key="t"
      variant="outline"
      :tone="t"
      :length="4"
      placeholder="·"
    >
      <XhPinInputLabel>{{ t }}</XhPinInputLabel>
      <div style="display: flex">
        <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
      </div>
    </XhPinInputRoot>
  </div>
</template>

尺寸

每格的边长随 size 换档，不传 size 即默认档

小

默认

大

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";

// 中间一档不写 size，用 undefined 表达
const sizes = [
  { size: "sm", label: "小" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "大" },
] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: flex-end; gap: 20px">
    <XhPinInputRoot v-for="s in sizes" :key="s.label" :size="s.size" :length="4" placeholder="·">
      <XhPinInputLabel>{{ s.label }}</XhPinInputLabel>
      <div style="display: flex">
        <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
      </div>
    </XhPinInputRoot>
  </div>
</template>

分组排布

格子由作者逐个写出，中间插什么都行；下标接着排，跳格与整串粘贴仍按文档序走

邀请码（3 + 3）

—

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhPinInputRoot :length="6" type="alphanumeric" placeholder="·">
    <XhPinInputLabel>邀请码（3 + 3）</XhPinInputLabel>
    <div style="display: flex; align-items: center">
      <XhPinInputInput v-for="i in 3" :key="'a' + i" :index="i - 1" />
      <span style="margin-inline: 8px">—</span>
      <XhPinInputInput v-for="i in 3" :key="'b' + i" :index="i + 2" />
    </div>
  </XhPinInputRoot>
</template>

填满才可提交

complete 在每格都有字时为真，作者据此点亮提交按钮；clear 一次清空整组

兑换码

四格都填满才能提交

<script setup lang="ts">
import { ref } from "vue";
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";

const submitted = ref("");

function reset(clear: () => void) {
  clear();
  submitted.value = "";
}
</script>

<template>
  <XhPinInputRoot v-slot="{ complete, valueAsString, clear }" :length="4" placeholder="·">
    <XhPinInputLabel>兑换码</XhPinInputLabel>
    <div style="display: flex">
      <XhPinInputInput v-for="i in 4" :key="i" :index="i - 1" />
    </div>
    <div style="display: flex; gap: 8px">
      <button type="button" :disabled="!complete" @click="submitted = valueAsString">
        提交
      </button>
      <button type="button" @click="reset(clear)">重填</button>
    </div>
    <span>{{ submitted ? "已提交：" + submitted : "四格都填满才能提交" }}</span>
  </XhPinInputRoot>
</template>

只读

格子带上原生 readonly，值走受控且宿主不回写：能聚焦、能选中复制，改不动

上一次的验证码

点进任意一格可以选中复制，敲键盘与粘贴都改不动它。

<script setup lang="ts">
import { XhPinInputInput, XhPinInputLabel, XhPinInputRoot } from "@xihan-ui/vue";

// 传了 value 就由宿主说了算，不回写值就恒定不变
const code = ["8", "1", "9", "2"];

// 皮肤没有只读档，底色由作者压下去表示改不动
const box = "background: var(--xh-bg-subtle)";
</script>

<template>
  <XhPinInputRoot :length="4" :value="code">
    <XhPinInputLabel>上一次的验证码</XhPinInputLabel>
    <div style="display: flex">
      <XhPinInputInput
        v-for="i in 4"
        :key="i"
        :index="i - 1"
        :style="box"
        readonly
      />
    </div>
  </XhPinInputRoot>
  <span>点进任意一格可以选中复制，敲键盘与粘贴都改不动它。</span>
</template>

产物

层	值
自定义元素	<xh-pin-input>
Vue 组件	XhPinInputHiddenInput XhPinInputInput XhPinInputLabel XhPinInputRoot
组合式函数	usePinInput
状态机	pinInputMachine
皮肤	@xihan-ui/styles/pin-input.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="pin-input"：root · label · input · hidden-input

Props

属性	类型	必填	说明
value	string[]		逐格的值。给定即受控：cell 直读 prop，写只发 onValueChange 不落内部值。
defaultValue	string[]
length	number		格数，默认 6。值的长度恒被归一到它。
type	PinInputType		接受的字符类别，默认 numeric。
mask	boolean		遮蔽显示：输入框转 type=password。
otp	boolean		一次性验证码：补 autocomplete=one-time-code，短信验证码才能被系统自动填入。
placeholder	string		空格子的占位字符。
disabled	boolean		禁用：每格都带原生 disabled（不可聚焦、不可输入），隐藏输入不参与提交。
invalid	boolean		校验失败标注。
blurOnComplete	boolean		填满即把焦点撤走，常用于"填满就自动提交"的表单。
name	string		表单字段名；给了隐藏输入才带 name，整串值随表单一并提交。
variant	ControlVariant		形态：outline / subtle / ghost，决定颜色怎么用。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色。
size	Size		尺寸：sm / md / lg。
translations	Partial<PinInputTranslations>
onValueChange	(details: PinInputValueChangeDetails) => void		value 变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。
onValueComplete	(details: PinInputValueChangeDetails) => void		每格都填满的那一刻触发；值没真变时不重复触发。

状态机

状态：idle

事件：VALUE.SET · VALUE.FILL · VALUE.CLEAR_AT · VALUE.CLEAR · INPUT.FOCUS · INPUT.BLUR · FORM.RESET

判据：canEdit

connect API

usePinInput 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
value	string[]	逐格的值，长度恒等于 length。
valueAsString	string
complete	boolean	每格都填满了。作者据此点亮提交按钮。
length	number
focusedIndex	number	焦点所在格；焦点在组外时为 -1。
disabled	boolean
invalid	boolean
setValue	(next: string[]) => void
clear	() => void
getRootProps	() => T['element']
getLabelProps	() => T['label']
getInputProps	(props: PinInputInputProps) => T['input']
getHiddenInputProps	() => T['input']	整份验证码的表单出口：一份 type=hidden 的原生输入，随表单提交拼好的串。

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowRight	focus in a box, not disabled	焦点移到下一格；已在末格则不动，不回绕
ArrowLeft	focus in a box, not disabled	焦点移到上一格；已在首格则不动，不回绕
Home	focus in a box, not disabled	焦点移到首格
End	focus in a box, not disabled	焦点移到末格
Backspace	focus in a box, not disabled	本格有值则清本格；本格为空则退回上一格并清掉上一格
Delete	focus in a box, not disabled	清掉本格，焦点不动