Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
InputOtp 验证码输入
一排单字符的输入格,用来输入短信验证码、动态口令这类固定位数的码。输入后自动跳到下一格,支持粘贴整段验证码和手机上的短信验证码自动填充。
引入
import { NsInputOtp } from '@ns/ui'
基础用法
用 v-model 绑定一个字符串,例如 '123456',没填时是空字符串。所有格子都填满时触发 finish,参数是完整的值,适合在这里直接提交。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp, NsMessage } from '@ns/ui'
const code = ref('')
const onFinish = (value: string) => {
NsMessage.success(`提交验证码 ${value}`)
}
</script>
<template>
<NsInputOtp v-model="code" @finish="onFinish" />
<p style="margin-top: 12px">绑定值:'{{ code }}'</p>
</template>
绑定值是已填的字符按顺序连起来的字符串。中间有空着的格子时不计入,例如第 3 格空着时值是 '12456';所以判断是否填完要看长度是否等于 length,或者直接用 finish 事件。
只允许数字
allow-input 判断每个字符能不能填进第 index 格(从 0 开始),返回 false 时忽略这个字符。纯数字验证码再加上 inputmode="numeric",手机上弹出数字键盘:
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp } from '@ns/ui'
const code = ref('')
</script>
<template>
<NsInputOtp v-model="code" :allow-input="(char) => /^\d$/.test(char)" inputmode="numeric" />
</template>
输入和粘贴都经过 allow-input。空格、换行等空白字符一律忽略,不用在 allow-input 里处理。index 可以用来给不同的格子定不同的规则,例如前两格只能填字母、后四格只能填数字:
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp } from '@ns/ui'
const code = ref('')
const allowInput = (char: string, index: number) =>
index < 2 ? /^[A-Za-z]$/.test(char) : /^\d$/.test(char)
</script>
<template>
<NsInputOtp v-model="code" :allow-input="allowInput" placeholder="AB1234" />
</template>
位数
length 是格子数,默认 6。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp, NsSpace } from '@ns/ui'
const four = ref('')
const six = ref('')
const eight = ref('')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">length = 4</span>
<NsInputOtp v-model="four" :length="4" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">6(默认)</span>
<NsInputOtp v-model="six" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">length = 8</span>
<NsInputOtp v-model="eight" :length="8" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 88px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
掩码和占位字符
mask 把输入的字符显示成圆点(每格是密码框)。placeholder 是空格子里的占位字符:只有一个字符时每格都显示它;多个字符时第 n 格显示第 n 个字符。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp, NsSpace } from '@ns/ui'
const pin = ref('123')
const code = ref('')
const date = ref('')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">mask</span>
<NsInputOtp v-model="pin" mask />
</NsSpace>
<NsSpace wrap>
<span class="row-label">一个字符</span>
<NsInputOtp v-model="code" placeholder="○" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">多个字符</span>
<NsInputOtp v-model="date" placeholder="YYMMDD" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
尺寸
size 有 large、default、small 三种。每一格是正方形,边长和同尺寸的输入框、按钮的高度一样:
| 尺寸 | 格子边长 | 字号 | 圆角 | 格子间距 |
|---|---|---|---|---|
| large | 40px | 16px | 8px | 12px |
| default | 32px | 14px | 6px | 8px |
| small | 24px | 12px | 4px | 6px |
不写 size 时依次跟随所在的 NsFormItem、NsForm、NsConfigProvider 的 size,都没有时是 default。下面每一行最后放一个同尺寸的按钮对比高度:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInputOtp, NsSpace } from '@ns/ui'
const code = ref('1234')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsInputOtp v-model="code" size="large" />
<NsButton size="large" type="primary">验证</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsInputOtp v-model="code" />
<NsButton type="primary">验证</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsInputOtp v-model="code" size="small" />
<NsButton size="small" type="primary">验证</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
间距和占满宽度
gap 改格子之间的间距,数字按 px,也可以写 '1rem' 这样的字符串。block 让组件占满父容器的宽度,格子平分宽度,高度不变。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp, NsSpace } from '@ns/ui'
const code = ref('')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsInputOtp v-model="code" :gap="4" />
<NsInputOtp v-model="code" :gap="16" />
<NsInputOtp v-model="code" gap="2rem" />
<NsInputOtp v-model="code" block />
</NsSpace>
</template>
禁用和只读
disabled 禁用所有格子,放在 NsForm 里时也跟随表单的 disabled。readonly 时能聚焦、能用方向键移动,不能输入、删除和粘贴。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp, NsSpace } from '@ns/ui'
const code = ref('123456')
const empty = ref('')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsInputOtp v-model="code" disabled />
<NsInputOtp v-model="empty" :length="4" placeholder="-" disabled />
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsInputOtp v-model="code" readonly />
<NsInputOtp v-model="empty" :length="4" placeholder="-" readonly />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
键盘类型
inputmode 决定手机上弹出哪种键盘,对应原生 input 的 inputmode,可选 text(默认)、numeric、decimal、tel、email、url、search、none(不弹键盘)。电脑上看不出区别,用手机打开本页,选一种再点格子试试:
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp, NsSegmented, NsSpace } from '@ns/ui'
import type { InputOtpInputMode } from '@ns/ui'
const modes: InputOtpInputMode[] = [
'text',
'numeric',
'decimal',
'tel',
'email',
'url',
'search',
'none'
]
const mode = ref<InputOtpInputMode>('numeric')
const code = ref('')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSegmented v-model="mode" :options="modes" size="small" />
<NsInputOtp v-model="code" :inputmode="mode" />
</NsSpace>
</template>
事件
用户输入、删除、粘贴使值变化时触发 change(和 update:modelValue 同时),填满所有格子时再触发 finish。focus、blur 只在焦点进出整个组件时触发,在格子之间移动不触发,第二个参数是格子的序号(从 0 开始)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputOtp } from '@ns/ui'
const code = ref('')
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (value: string) => log(`change:'${value}'`)
const onFinish = (value: string) => log(`finish:'${value}'`)
const onFocus = (_event: FocusEvent, index: number) => log(`focus:第 ${index + 1} 格`)
const onBlur = (_event: FocusEvent, index: number) => log(`blur:第 ${index + 1} 格`)
</script>
<template>
<NsInputOtp
v-model="code"
:length="4"
@change="onChange"
@finish="onFinish"
@focus="onFocus"
@blur="onBlur"
/>
<p style="margin-top: 12px">最近的事件(新的在前):{{ logs.join(',') || '还没有' }}</p>
</template>
校验状态
组件没有单独的状态属性,出错的样子由所在的 NsFormItem 决定:校验不通过,或者给表单项传了 error 时,每一格的边框都变成危险色,下面显示错误信息。
<script setup lang="ts">
import { ref } from 'vue'
import { NsForm, NsFormItem, NsInputOtp, NsSwitch } from '@ns/ui'
const showError = ref(true)
const code = ref('1234')
</script>
<template>
<NsSwitch v-model="showError" active-text="显示错误" />
<NsForm label-width="80px" style="margin-top: 16px" @submit.prevent>
<NsFormItem label="验证码" :error="showError ? '验证码不正确,请重新输入' : ''">
<NsInputOtp v-model="code" />
</NsFormItem>
</NsForm>
</template>
在表单里
放在 NsFormItem 里时和其他表单控件一样:
- 标签的
for指向第一格,点标签聚焦第一格;整组用aria-labelledby关联标签。 - 值变化时触发
change规则;焦点离开整个组件(不是在格子之间移动)时触发blur规则。validateEvent设为false可以关掉这两种触发。 - 校验出错时每一格的边框都变红。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInputOtp } from '@ns/ui'
const form = reactive({ code: '' })
const rules = {
code: [
{ required: true, message: '请输入验证码', trigger: 'blur' },
{ min: 6, message: '验证码是 6 位', trigger: 'blur' }
]
}
</script>
<template>
<NsForm :model="form" :rules="rules">
<NsFormItem label="验证码" prop="code">
<NsInputOtp v-model="form.code" inputmode="numeric" />
</NsFormItem>
</NsForm>
</template>
键盘操作
| 按键 | 作用 |
|---|---|
| 输入字符 | 填进当前格,跳到下一格;最后一格填完后焦点留在最后一格 |
| 退格 | 当前格有字符时删掉它,焦点不动;当前格已空时删前一格并移过去 |
| Delete | 删当前格,焦点不动 |
| ← → | 移到前一格、后一格,到两端不再动 |
| Home、End | 移到第一格、最后一格 |
| Tab | 按顺序经过每一格 |
| 粘贴 | 从当前格开始依次填入,跳过不允许的字符,填满后多出来的丢弃 |
聚焦(包括点击、方向键移过去)时选中格子里的字符,接着输入会直接替换它。
短信验证码自动填充
第一格带 autocomplete="one-time-code",iOS、Android 的键盘上会提示收到的短信验证码,点一下会把整段验证码填进第一格,组件把它依次分到各格(和粘贴一样经过 allow-input)。其余格子是 autocomplete="off"。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | '' | 绑定值,支持 v-model。已填的字符按顺序连起来的字符串,空着的格子不计入 |
| length | number | 6 | 格子数。小数向下取整;小于 1、NaN、Infinity 时按 6 处理并在控制台警告 |
| mask | boolean | false | 是否把输入的字符显示成圆点 |
| placeholder | string | '' | 空格子里的占位字符:一个字符时每格都显示,多个字符时第 n 格显示第 n 个 |
| allowInput | (char: string, index: number) => boolean | - | 判断字符能不能填进第 index 格(从 0 开始),返回 false 时忽略;输入和粘贴都经过它 |
| gap | number | string | - | 格子间距,数字按 px;不写时按尺寸是 12 / 8 / 6px |
| block | boolean | false | 是否占满父容器的宽度,格子平分宽度 |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读:能聚焦、能移动,不能输入、删除和粘贴 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 default |
| inputmode | InputOtpInputMode | 'text' | 手机上弹出的键盘类型,纯数字验证码用 'numeric' |
| validateEvent | boolean | true | 值变化和焦点离开组件时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string) | 输入、删除、粘贴使值变化时触发,v-model 用 |
| change | (value: string) | 用户操作使值变化时触发,和 update:modelValue 同时;外部改值不触发 |
| finish | (value: string) | 用户操作后所有格子都填满时触发,参数是完整的值;值没变时不重复触发 |
| focus | (event: FocusEvent, index: number) | 焦点从组件外面进入第 index 格时触发;在格子之间移动不触发 |
| blur | (event: FocusEvent, index: number) | 焦点离开整个组件时触发,index 是离开前所在的格子;格子之间移动不触发 |
Slots
无。
方法
通过 NsInputOtp 的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| focus | (index?: number) | void | 聚焦第 index 格(从 0 开始,超出范围时停在两端);不传时聚焦第一个空格子,都填满时聚焦最后一格 |
| blur | - | void | 让当前聚焦的格子失去焦点 |
例如重新发送验证码后清空并聚焦第一格。下面几个按钮分别调用 focus()、focus(2)、blur():
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInputOtp, NsSpace } from '@ns/ui'
const code = ref('12')
const otpRef = ref<InstanceType<typeof NsInputOtp>>()
const resend = () => {
code.value = ''
otpRef.value?.focus(0)
}
</script>
<template>
<NsInputOtp ref="otpRef" v-model="code" />
<div style="margin-top: 12px">
<NsSpace wrap>
<NsButton type="primary" @click="resend">重新发送(清空并聚焦第一格)</NsButton>
<NsButton @click="otpRef?.focus()">聚焦第一个空格子</NsButton>
<NsButton @click="otpRef?.focus(2)">聚焦第 3 格</NsButton>
<NsButton @click="otpRef?.blur()">失焦</NsButton>
</NsSpace>
</div>
</template>
类型
import type { InputOtpProps, InputOtpEmits, InputOtpSize, InputOtpInputMode } from '@ns/ui'
type InputOtpSize = 'large' | 'default' | 'small'
type InputOtpInputMode =
| 'text'
| 'numeric'
| 'decimal'
| 'tel'
| 'email'
| 'url'
| 'search'
| 'none'
注意事项
- 每一格是一个原生
<input>,类名是ns-input-otp__input,aria-label是“第 n 位”;整组是role="group"的div(ns-input-otp)。class、style、aria-label等属性留在整组上,id放在第一格上(和表单项标签的for一致)。 - 绑定值里没有空格子的位置信息:外部把值改成另一个字符串时按新值从第一格开始重新排;组件自己发出的值回传回来时格子不动(中间空着的格子保持空着)。
length变小时多出来的字符不显示,绑定值不会被自动截断;绑定值比length长时同样只显示前length个字符。mask用的是浏览器的密码框,有的浏览器会提示保存密码。Edge 密码框里的“显示密码”按钮已经隐藏。- 手机键盘的退格有时不发出
keydown(安卓的部分输入法),这时格子有字符能正常删除,格子已空时不会跳回前一格,需要点前一格再删。 - 中文输入法组合输入期间不处理,上屏后再填进格子。