KeyboardPassword 密码键盘

底部弹层形态的支付密码键盘：固定位数密码位回显（实心圆点 + 下一格品牌色描边）+ 数字键区（randomKey 打乱防窥）+ 右侧删除 / 完成功能列。用于支付密码、支付 PIN 等不想调起系统输入法、且输入进度需要在拇指上方可见的录入场景。

平台兼容性

App	Web	微信小程序
✓	✓	✓

基础用法

<n-keyboard-password
	v-model="password"
	:visible="show"
	title="请输入支付密码"
	:close-on-mask="false"
	complete-text="支付"
	@close="show = false"
	@complete="onPay"
/>

const show = ref(false);
const password = ref("");

function onPay() {
	// 支付请求进行中锁完成键防重复提交
	paying.value = true;
	// ...校验 password（满 length 位与否由业务判断）并提交
}

值走 v-model 明文数字串（回显恒为圆点，不提供明文回显）；满 length 位后按键不再拼接但 input 事件仍上报。传输与加密由业务侧处理。

API

Props

属性	类型	说明
visible	boolean	显隐开关（受控模式：组件不自行收起，隐藏由使用者在回调里改回 false），默认 false
modelValue	string	已输入密码（v-model，明文数字串）：按键自动拼接、退格去尾；回显恒为圆点，默认 ""
length	number	密码位数：回显格数与输入硬上限，小于 1 按 1 处理；支付密码通常 6，默认 6
randomKey	boolean	每次打开时打乱数字键位（0-9 位置随机重洗），当众输密码防窥场景开启，默认 false
title	string	标题栏文字（如 "请输入支付密码"），空串不渲染标题栏，默认 ""
showClose	boolean	标题栏右侧显示关闭按钮（点击派发 close），默认 false
closeOnMask	boolean	点击遮罩派发 close；支付密码场景建议关闭强制走完成校验，默认 true
completeText	string	完成键文案（支付场景传 "支付"），空串用库内置文案（随库语言包），默认 ""
disabled	boolean	完成键禁用（支付请求进行中锁定防重复提交）：保色相降透明度 + 点击守卫，默认 false
customClass	string	挂到根节点的额外 class，默认 ""
customStyle	string	根节点行内样式（作用于全屏遮罩层），默认 ""
panelStyle	string	微调底部面板的行内样式，如 "background-color:#111111"，默认 ""

Events

事件	参数	说明
update:modelValue	value: string	按键拼接 / 退格去尾后的新值（v-model 通道；满 length 位不拼接时不发）
input	key: string	点击数字键时触发（满位时仍上报），参数为键值字符
delete	e: Event	点击删除键时触发（值已自动去尾；不绑 v-model 则自行去位）
close	—	点击遮罩（closeOnMask 开启时）或标题栏关闭按钮时触发
complete	e: Event	点击完成键时触发（disabled 锁定时不派发；组件不自行收起）

实现说明

与参考实现（同类密码 / 数字键盘）的机制对照：

机制	参考做法	本库做法
键位乱序	random 开关，每次打开重洗	同款 randomKey（Fisher-Yates 重洗 0-9，每次打开 / 开关翻转时重洗，关闭回标准布局——与 n-keyboard-number 同一实现）
密码位回显	键盘内文字行回显（明文 / 星号可切）；或键盘不带回显、由外部密码输入框组件承担	固定位数格子回显：实心圆点（view 绘制非字符，无行高裁剪问题）+ 下一格品牌色描边（只换颜色不换宽度，格宽不抖动）；弹层常遮挡页面输入区，进度必须在拇指上方可见（车牌键盘回显条同一条理由）
完成语义	键盘内校验位数并 toast 后回写 / 收起；或纯上报由业务处理	纯上报（complete 携带事件，v-model 值业务侧自取）：位数是否满足、密码是否正确、重试逻辑全部业务侧处理——键盘族契约「组件只管单字符，组合语义业务侧校验」
完成键防重复提交	disabled 锁完成键	同款 disabled：保色相降透明度（深浅主题与品牌色都保得住）+ JS 守卫拦截点击不派发
值通道	逐键上报拼值 / 确认时一次性回写双模式	与 n-keyboard-number 同构的 v-model 双通道：逐键自动拼接 / 退格（满 length 位不拼接但 input 仍上报），不绑 v-model 也可只用语义事件自行拼值
硬上限不变量	参考实现不改写既有值	length 收紧或外部写入超限值时组件自动截断收敛并回写 v-model（n-number-box 越界夹取同职责）——固定位回显格只显示 length 格，若放任更长值存在，complete 会带着不可见的超限密码误载
显隐模式	show 受控 + 组件自行收起 / open()/close() 方法式	受控 visible + 事件上报（close / complete 都不自行收起，显隐由使用者改 visible——显式优于隐式，n-tag 同一契约）
键盘形态	QWERTY 全键盘（字母 + 符号 + 大小写）；数字键盘 + 小数点 / 00 / X	纯数字 3×4 + 右侧删除 / 完成功能列（支付密码 = 定长数字串，字母 / 符号位属「安全键盘」另一形态；小数点 / 00 是金额语义、X 是身份证语义，归 n-keyboard-number 的 mode）
未采纳	工具条取消按钮（标题栏 + showClose 已覆盖退出通道）；备用键 spareKey（车牌 / 身份证场景，归数字键盘 mode）；明文回显 / 回显开关 / 回显插槽 #value（密码组件明文回显是安全反模式，回显形态即组件核心价值，全定制走 panelStyle）；按键震动（业务侧在 input / complete 回调里调 uni.vibrateShort，通道更干净）；主题 prop（库令牌自动跟随）	见左列说明