InputOtp 一次性密码输入

avue-input-otp 基于 Element Plus 的 OTP 输入框封装，适用于短信验证码、动态口令等分段输入场景。Form 与 Crud 的列配置可通过 type: 'otp' 或 type: 'input-otp' 使用。

独立组件与字段配置的区别见 基础组件使用约定。OTP 始终使用字符串绑定值，避免验证码开头的 0 被数值转换丢失。

基础用法

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space direction="vertical" alignment="flex-start" :size="16">
    <avue-input-otp
      v-model="otp"
      :length="4"
      otp-type="filled"
      inputmode="numeric"
      :validator="isNumber"
      @finish="handleFinish"
    />
    <span>当前值：{{ otp || '未输入' }}</span>
    <el-button @click="otp = ''">清空</el-button>
  </el-space>
</template>

<script setup>
import { ref } from 'vue';
import { ElMessage } from 'element-plus';

const otp = ref('');

const isNumber = (value) => /^\d$/.test(value);

const handleFinish = ({ value }) => {
  ElMessage.success(`验证码输入完成：${value}`);
};
</script>

外观、掩码与分隔符

otpType 可切换三种外观；通过 mask 隐藏输入内容，separator 可在输入格之间显示分隔符。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space direction="vertical" alignment="flex-start" :size="16">
    <avue-input-otp
      v-model="otp"
      :length="6"
      :otp-type="otpType"
      :mask="mask"
      :separator="showSeparator ? '-' : undefined"
      inputmode="numeric"
      :validator="isNumber"
    />
    <el-space wrap>
      <el-radio-group v-model="otpType">
        <el-radio-button label="outlined">描边</el-radio-button>
        <el-radio-button label="filled">填充</el-radio-button>
        <el-radio-button label="underlined">下划线</el-radio-button>
      </el-radio-group>
      <el-switch v-model="mask" active-text="掩码" />
      <el-switch v-model="showSeparator" active-text="显示分隔符" />
    </el-space>
    <span>当前值：{{ otp || '未输入' }}</span>
  </el-space>
</template>

<script setup>
import { ref } from 'vue';

const otp = ref('123456');
const otpType = ref('outlined');
const mask = ref(false);
const showSeparator = ref(false);
const isNumber = (value) => /^\d$/.test(value);
</script>

实例方法控制

通过 ref 可以主动聚焦指定输入格或取消聚焦，适合配合“重新发送验证码”等交互使用。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space direction="vertical" alignment="flex-start" :size="16">
    <avue-input-otp
      ref="otpRef"
      v-model="otp"
      :length="6"
      inputmode="numeric"
      :validator="isNumber"
      :disabled="disabled"
      :readonly="readonly"
    />
    <el-space wrap>
      <el-button type="primary" @click="focus()">聚焦首格</el-button>
      <el-button @click="focus(3)">聚焦第 4 格</el-button>
      <el-button @click="blur">取消聚焦</el-button>
      <el-button @click="otp = ''">清空</el-button>
      <el-switch v-model="readonly" active-text="只读" />
      <el-switch v-model="disabled" active-text="禁用" />
    </el-space>
    <span>当前值：{{ otp || '未输入' }}</span>
  </el-space>
</template>

<script setup>
import { ref } from 'vue';

const otpRef = ref();
const otp = ref('123456');
const readonly = ref(false);
const disabled = ref(false);
const isNumber = (value) => /^\d$/.test(value);

const focus = (index) => otpRef.value?.focus(index);
const blur = () => otpRef.value?.blur();
</script>

Attributes

参数	说明	类型	可选值	默认值
modelValue / v-model	绑定的一次性密码	string	-	-
length	输入格数量	number	-	6
validator	单个字符校验函数，返回 false 时不接受输入	function	-	-
inputmode	原生输入模式	string	numeric 等	-
otpType	输入框外观类型	string	outlined / filled / underlined	outlined
mask	是否掩码显示	boolean	true / false	false
separator	分隔符，可传文本、VNode 或渲染函数	string / object / function	-	-
validateEvent	是否触发表单校验	boolean	true / false	true
disabled	是否禁用	boolean	true / false	false
readonly	是否只读	boolean	true / false	false
size	组件尺寸	string	large/default/small	-
id	输入框 ID	string	-	-
ariaLabel	无障碍标签	string	-	-
finish	输入完成回调	function	-	({ value }) => {}

Events

事件名	说明	回调参数
finish	输入达到 length 时触发	{ value, column, dic, item }
change	底层控件 change 时触发，与逐字符 v-model 更新分开	{ value, column, dic, item }
focus	获得焦点时触发	{ value, event, column, dic, item }
blur	失去焦点时触发	{ value, event, column, dic, item }

Methods

通过组件 ref 调用。

方法名	说明	参数
focus	聚焦 OTP 输入框	index?: number，可指定聚焦的输入格
blur	取消聚焦	-
inputRefs	OTP 原生输入框引用列表，只读属性，不是函数	-

Form / Crud 列配置

Form 中可直接完成输入与校验；Crud 的 cell: true 可让 OTP 作为单元格编辑控件使用。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <p class="input-otp-form-crud__value">Form 当前值：{{ form.otp || '未输入' }}</p>
  <avue-form v-model="form" :option="formOption" />

  <el-divider content-position="left">Crud 单元格编辑</el-divider>
  <avue-crud :data="crudData" :option="crudOption" />
</template>

<script setup>
import { ref } from 'vue';
import { ElMessage } from 'element-plus';

const isNumber = (value) => /^\d$/.test(value);
const showFinished = ({ value }) => ElMessage.success(`验证码输入完成：${value}`);

const form = ref({ otp: '' });
const formOption = {
  submitBtn: false,
  emptyBtn: false,
  column: [
    {
      label: '短信验证码',
      prop: 'otp',
      type: 'otp',
      length: 6,
      otpType: 'filled',
      inputmode: 'numeric',
      validator: isNumber,
      rules: [{ required: true, message: '请输入 6 位验证码', trigger: 'blur' }],
      finish: showFinished,
    },
  ],
};

const crudData = ref([
  { id: 1, account: 'smallwei', otp: '2468' },
]);
const crudOption = {
  border: true,
  menu: false,
  addBtn: false,
  column: [
    { label: '账号', prop: 'account' },
    {
      label: '一次性密码',
      prop: 'otp',
      type: 'input-otp',
      length: 4,
      otpType: 'underlined',
      mask: true,
      cell: true,
      inputmode: 'numeric',
      validator: isNumber,
      finish: showFinished,
    },
  ],
};
</script>

<style scoped>
.input-otp-form-crud__value {
  margin-bottom: 12px;
  color: var(--el-text-color-secondary);
}
</style>

{
  label: '验证码',
  prop: 'otp',
  type: 'otp', // 也可写为 input-otp
  length: 6,
  otpType: 'filled',
  inputmode: 'numeric',
  validator: (value) => /^\d$/.test(value),
  finish: ({ value }) => {
    console.log('输入完成：', value)
  }
}