BizVerifyCodeInput 验证码输入

短信 / 邮箱验证码分格输入（OTP）：多 input 逐格方案，输入自动跳格、退格回跳、整段粘贴自动分发、左右方向键移动、字符类型过滤（type）、密码圆点遮显（mask）、错误态红框抖动（error）、内置重发倒计时按钮。输满自动触发 complete。登录 / 注册二次验证、换绑手机邮箱、支付密码、敏感操作复核。

基础用法

-

当前值：（未输入）　·　支持整段粘贴自动分发

v-model 单字符串值；separator-at 在指定格后显示分隔符（6 位码 3+3）；输满触发 complete。

<script setup lang="ts">
/** 场景：换绑手机——基础 6 位输入，complete 输满自动提交提示，v-model 回显 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizVerifyCodeInput } from 'vue3-ep-biz-lib'

const code = ref('')

const onComplete = (value: string): void => {
  ElMessage.success(`验证码已输满：${value}（此处调用校验接口）`)
}
</script>

<template>
  <div style="max-width: 420px">
    <BizVerifyCodeInput v-model="code" :separator-at="3" @complete="onComplete" />
    <p style="margin-top: 10px; font-size: 13px; color: #909399">
      当前值：{{ code || '（未输入）' }}　·　支持整段粘贴自动分发
    </p>
  </div>
</template>

显示代码

纯数字过滤

4 位纯数字（字母无法输入，移动端唤起数字键盘）

type="number" 仅数字可输入（字母被过滤），移动端 inputmode 唤起数字键盘；length 自定义格数。

<script setup lang="ts">
/** 场景：纯数字短信码——type=number 过滤非法字符，numeric 键盘唤起 */
import { ref } from 'vue'
import { BizVerifyCodeInput } from 'vue3-ep-biz-lib'

const code = ref('')
</script>

<template>
  <div style="max-width: 420px">
    <BizVerifyCodeInput v-model="code" type="number" :length="4" />
    <p style="margin-top: 10px; font-size: 13px; color: #909399">
      4 位纯数字（字母无法输入，移动端唤起数字键盘）
    </p>
  </div>
</template>

显示代码

密码遮显与尺寸

largedefaultsmall

密码态圆点遮显（输入值仍可通过 v-model 获取）

mask 圆点遮显（值仍经 v-model 获取），size 三档尺寸（对齐 Element Plus）。

<script setup lang="ts">
/** 场景：支付密码——mask 圆点遮显 + 尺寸切换 */
import { ref } from 'vue'
import { ElRadioButton, ElRadioGroup } from 'element-plus'
import { BizVerifyCodeInput } from 'vue3-ep-biz-lib'
import type { BizVerifyCodeSize } from 'vue3-ep-biz-lib'

const code = ref('')
const size = ref<BizVerifyCodeSize>('large')
</script>

<template>
  <div style="max-width: 420px">
    <ElRadioGroup v-model="size" style="margin-bottom: 12px">
      <ElRadioButton value="large">large</ElRadioButton>
      <ElRadioButton value="default">default</ElRadioButton>
      <ElRadioButton value="small">small</ElRadioButton>
    </ElRadioGroup>
    <BizVerifyCodeInput v-model="code" mask :size="size" :length="6" />
    <p style="margin-top: 10px; font-size: 13px; color: #909399">
      密码态圆点遮显（输入值仍可通过 v-model 获取）
    </p>
  </div>
</template>

显示代码

重发倒计时

show-resend 内置重发按钮：点击外抛 resend（调发送接口）并自动进入倒计时，resend-seconds 自定义秒数。

<script setup lang="ts">
/** 场景：登录二次验证——内置重发倒计时按钮，resend 外抛调接口 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizVerifyCodeInput } from 'vue3-ep-biz-lib'

const code = ref('')

const onResend = (): void => {
  ElMessage.success('已调用短信发送接口（组件自动进入 30s 倒计时）')
}
</script>

<template>
  <div style="max-width: 420px">
    <BizVerifyCodeInput
      v-model="code"
      type="number"
      show-resend
      :resend-seconds="30"
      resend-text="重新获取验证码"
      @resend="onResend"
    />
  </div>
</template>

显示代码

错误态

输满校验，正确码为 123456；错误时红框 + 抖动，继续输入自动消除

error 置 true 触发红框 + 一次抖动动画；业务在 complete 里校验，重新输入时自行置回 false。

<script setup lang="ts">
/** 场景：校验失败——complete 后校验不对标 error 抖动，重新输入自动消除错误态 */
import { ref } from 'vue'
import { BizVerifyCodeInput } from 'vue3-ep-biz-lib'

const code = ref('')
const error = ref(false)

const onComplete = (value: string): void => {
  if (value !== '123456') {
    error.value = true
  }
}
</script>

<template>
  <div style="max-width: 420px">
    <BizVerifyCodeInput
      v-model="code"
      :error="error"
      @complete="onComplete"
      @update:model-value="error = false"
    />
    <p style="margin-top: 10px; font-size: 13px; color: #909399">
      输满校验，正确码为 123456；错误时红框 + 抖动，继续输入自动消除
    </p>
  </div>
</template>

显示代码

外部控制

禁用

只读

autofocus 自动聚焦；expose focus（聚焦第一空格）/ clear（清空并聚焦）；禁用与只读态。

<script setup lang="ts">
/** 场景：外部控制——autofocus 自动聚焦、focus / clear expose、禁用只读态 */
import { ref } from 'vue'
import { ElButton, ElSwitch } from 'element-plus'
import { BizVerifyCodeInput } from 'vue3-ep-biz-lib'
import type { BizVerifyCodeInputInstance } from 'vue3-ep-biz-lib'

const code = ref('')
const disabled = ref(false)
const readonly = ref(false)
const inputRef = ref<BizVerifyCodeInputInstance>()
</script>

<template>
  <div style="max-width: 460px">
    <BizVerifyCodeInput
      ref="inputRef"
      v-model="code"
      autofocus
      :disabled="disabled"
      :readonly="readonly"
    />
    <div style="margin-top: 12px; display: flex; align-items: center; gap: 12px">
      <ElButton size="small" @click="inputRef?.focus()">聚焦第一空格</ElButton>
      <ElButton size="small" @click="inputRef?.clear()">清空</ElButton>
      <span style="font-size: 13px">禁用</span>
      <ElSwitch v-model="disabled" />
      <span style="font-size: 13px">只读</span>
      <ElSwitch v-model="readonly" />
    </div>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
v-model	string	''	输入值（单字符串，长度等于 length）
length	number	6	格数
type	'number' | 'letter' | 'mixed'	'mixed'	字符类型过滤：纯数字 / 纯字母 / 字母数字
mask	boolean	false	密码态：圆点遮显
size	'large' | 'default' | 'small'	'default'	尺寸
disabled	boolean	false	整体禁用
readonly	boolean	false	只读
autofocus	boolean	false	挂载后自动聚焦第一格
error	boolean	false	错误态：红框；置 true 时触发一次抖动动画
separator-at	number	—	在第 N 格后显示分隔符（如 6 位码传 3）
separator	string	'-'	分隔符文案
show-resend	boolean	false	内置重发倒计时按钮
resend-text	string	'重新发送验证码'	重发按钮文案
resend-seconds	number	60	倒计时秒数

Events

事件名	参数	说明
update:model-value	(value: string)	输入值变化（v-model）
complete	(value: string)	输满最后一格时触发（自动失焦）
resend	()	点击重发按钮（组件同时自动开始倒计时）

Expose

名称	类型	说明
focus	() => void	聚焦第一个空格
blur	() => void	所有格失焦
clear	() => void	清空全部格并聚焦首格
startCountdown	() => void	手动启动重发倒计时（如接口返回后）

TIP

与 BizSliderCaptcha 组合使用覆盖人机验证 + 动态码双重校验场景；重发倒计时能力独立于 BizCountdownButton（本组件内聚为输入区附属按钮形态）。