更新记录

1.0.0（2026-09-09） 下载此版本

1. 首次发布：验证码/一次性 PIN 输入组件（透明 input + N 格展示，功能与原 m-verification-code 完全一致）
2. v-model 双向绑定：支持 modelValue / value，输入自动截断至 length 位，填满触发 complete
3. 分隔横线可配置：middle（中间一条）/ between（格子间）/ none，颜色/宽/高可调
4. 聚焦高亮与填满变色：focusColor 高亮待填格子，filledBorderColor 标记已填格子
5. 样式全面可配：格子数量/宽高/圆角、边框颜色粗细、字体/字号/字重/颜色；inputType / disabled 可配
6. 事件完整：update:modelValue / input / change / complete / focus / blur
7. 新增输入净化：sanitize（默认开启）过滤粘贴/特殊字符；number 类型仅保留数字，文本类型去除空白/控制/零宽字符；allowChars 可自定义允许字符集
8. 点击已填格子从该格起清空并聚焦重输（clickToEdit，默认开启），点击空格子聚焦
9. defineExpose 暴露实例方法：clear() / focus() / blur()，便于校验失败后清空重置高亮

平台兼容性

uni-app(5.24)

其他

Pin Code 验证码输入框

一款基于 uni-app（Vue3）的验证码 / 一次性 PIN 输入组件。采用透明 input 采集 + N 个展示格子的方案：点击任意格子区域即可聚焦输入，支持聚焦高亮、填满后边框变色、分隔横线与整体尺寸/颜色/字体可配置，并支持 v-model 与 complete 等事件，开箱即用。

🚀 功能特性

• ✅ v-model 双向绑定：支持 modelValue / value，输入自动同步
• ✅ 输入自动截断：最多保留 length 位，填满自动触发 complete
• ✅ 分隔横线可配置：middle（中间一条）/ between（格子之间）/ none（无），颜色/宽/高可配
• ✅ 聚焦高亮：点击任意格子区域聚焦，当前待填格子边框高亮（focusColor）
• ✅ 填满状态反馈：已填入内容的格子边框自动变色（filledBorderColor）
• ✅ 样式全面可配：格子数量/宽高/圆角、边框颜色粗细、字体/字号/字重/颜色
• ✅ 输入方式可配：inputType（默认 number 数字键盘）、disabled 禁用
• ✅ 事件完整：input / change / complete / focus / blur
• ✅ 输入净化：数字输入仅保留数字；文本输入过滤空白/控制/零宽不可见字符；支持 allowChars 自定义允许字符集
• ✅ 点击定位重输：点击已填格子从该格起清空并聚焦重输，点击空格子直接聚焦
• ✅ 实例方法：通过 ref 调用 clear() / focus() / blur()，便于校验失败后重置
• ✅ 多端适配：纯 view/text + 原生 input，适配 H5 / App-vue / 小程序

📦 安装引入

1. 将 uni_modules/pin-code 整个目录复制到项目的 uni_modules 目录下；
2. 开启 easycom 时可直接使用 <pin-code> 标签，无需手动引入；
3. 若未开启 easycom，可在页面中手动引入：

<script setup>
import PinCode from "@/uni_modules/pin-code/components/pin-code/pin-code.vue";
</script>

🚀 快速开始

<template>
  <view>
    <!-- 基础用法：默认 6 格，输满触发 complete -->
    <pin-code v-model="code" @complete="onComplete" />

    <!-- 进阶用法：4 格 + 格间横线 + 自定义高亮色 -->
    <pin-code
      v-model="code4"
      :length="4"
      separator-mode="between"
      focus-color="#29CA8B"
    />
  </view>
</template>

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

const code = ref("");
const code4 = ref("");

const onComplete = (value) => {
  console.log("验证码已填满：", value);
};
</script>

🔧 Props 属性配置

分隔横线

方框与边框

文字样式

📡 Events 事件

🧰 实例方法

给组件加 ref 后可调用（多用于"校验失败重置"场景）：

<template>
  <pin-code ref="codeRef" v-model="code" @complete="handleCode" />
</template>

<script setup>
import { ref } from "vue";
const code = ref("");
const codeRef = ref(null);

const handleCode = async (val) => {
  try {
    // ... 校验
  } catch {
    // 校验失败：清空内容并失焦，避免高亮/键盘残留
    codeRef.value?.clear?.();
  }
};
</script>

🎨 样式自定义

组件内部类可在外部覆盖（scoped 样式需 :deep() 穿透）：

<style lang="scss" scoped>
:deep(.verification-code__box) {
  background: #f6f7f9;
}
</style>

⚠️ 使用注意事项

1. 数据源：优先使用 v-model（modelValue）；value 仅为旧用法兼容，两者都传时以 modelValue 为准
2. 输入截断：内容超过 length 会自动截断；输满后再次输入相同长度不会重复触发 complete
3. 输入净化：默认开启（sanitize=true）。inputType=number 只保留数字；其它类型只去掉空白/控制/零宽不可见字符。若需严格白名单（如邀请码只允许字母数字）传 allow-chars="0-9a-zA-Z"；希望完全不过滤则传 :sanitize="false"
4. 点击重输：点击已填写的格子会从该格起清空并聚焦重输（clickToEdit，默认开启）；点击空格子仅聚焦。如不希望点击修改内容可传 :click-to-edit="false"
5. 分隔模式：middle 模式下横线位置取 floor(length / 2)，偶数位居中、奇数位偏右，符合常规验证码样式
6. 聚焦行为：点击组件任意位置会聚焦透明输入框；disabled 时点击无效
7. 避免与组件标签同名：页面（<script setup>）内不要定义与标签同名的局部变量或函数（如 pinCode），否则 Vue 编译时局部变量优先于 easycom 组件，<pin-code> 会被解析成该局部变量而非组件，请使用不与标签冲突的命名

📞 更新日志

v1.0.1（2026-09-09）

• 🆕 输入净化：sanitize（默认开启）过滤粘贴/特殊字符，数字输入仅保留数字，文本输入去除空白与零宽字符；allowChars 可自定义允许字符集
• 🆕 点击已填格子从该格起清空重输（clickToEdit，默认开启）
• 🆕 新增实例方法 clear() / focus() / blur()（defineExpose）
• 行为兼容：默认配置下与原 v1.0.0 一致，不影响现有用法

v1.0.0（2026-09-09）

• 🎉 首个版本发布：以 uni_modules 插件（easycom 自动引入）形态封装验证码输入组件
• 支持 v-model（modelValue / 兼容 value），输满自动触发 complete，并派发 input / change / focus / blur
• 透明 input + N 格展示方案，点击任意位置聚焦，待填格子高亮、已填格子边框变色
• 格子数量 / 宽高 / 圆角、边框颜色粗细、focusColor / filledBorderColor 均可配置
• 分隔横线：middle（中间一条）/ between（格间）/ none，颜色 / 宽 / 高可配置
• 字体族 / 字号 / 字重 / 颜色、inputType（默认 number 数字键盘）、disabled 禁用均可配置

祝您使用愉快！ 🎉