xtf-number-keyboard

组件说明

xtf-number-keyboard 是可绑定输入值的数字键盘，适用于支付密码、金额和验证码输入。支持触发器插槽、随机键位、完成自动关闭及多种容器形态。

---

基础用法

1. 受控显示

<template>
  <view>
    <xtf-button label="输入金额" @click="show = true" /><xtf-number-keyboard
      v-model="value"
      v-model:show="show"
      @confirm="confirm"
  /></view>
</template>
<script>
export default {
  data() {
    return { show: false, value: '' }
  },
  methods: {
    confirm(value) {
      console.log('金额', value)
    }
  }
}
</script>

2. 密码输入与自动完成

<template>
  <xtf-number-keyboard
    v-model="password"
    :show="true"
    secure-mode
    random-key-order
    :maxlength="6"
    close-on-input-complete
    @complete="complete"
  />
</template>
<script>
export default {
  data() {
    return { password: '' }
  },
  methods: {
    complete(value) {
      uni.showToast({ title: '已输入 ' + value.length + ' 位', icon: 'none' })
    }
  }
}
</script>

3. 自定义触发器插槽

<template>
  <xtf-number-keyboard v-model="amount" v-model:show="show" show-trigger extra-key=".">
    <template #trigger="{ value, openKeyboard }">
      <xtf-cell title="付款金额" :value="value || '点击输入'" arrow @click="openKeyboard"
    /></template>
  </xtf-number-keyboard>
</template>
<script>
export default {
  data() {
    return { amount: '', show: false }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
modelValue	String	''	当前输入值	v-model
show	Boolean	false	是否显示键盘	v-model:show
theme	String	'default'	default/soft/card/contrast/dark/custom；dark 为黑色按键与蓝色确认键布局。	视觉变体
keyboardType	String	'number'	number 数字键盘 / password 密码数字键盘 / id-card 身份证键盘（提供 X）/ province 省份简称十列键盘。	金额、密码、身份信息、车牌省份等不同输入场景。
showDoubleZero	Boolean	false	数字键盘是否增加 00 按键；仅 keyboardType='number' 生效。	金额和快速金额录入。
maxlength	Number | String	Infinity	最大字符数	密码、验证码
closeOnInputComplete	Boolean	false	达到长度时自动关闭	固定长度输入
extraKey	String | Array | Boolean	false	左下角额外键，false 留空	小数输入
closeButtonText	String	'完成'	完成按键文案	文案定制
deleteButtonText	String	'删除'	删除文案配置，当前图标按钮仍使用图标	文案兼容
overlay	Boolean	true	sheet/card 模式遮罩	模态输入
closeOnClickOverlay	Boolean	true	点击遮罩是否关闭	遮罩交互
lockScroll	Boolean	false	是否锁定 H5 页面滚动	弹出键盘
randomKeyOrder	Boolean	false	随机排列 1-9	安全输入
randomAllNumbers	Boolean	false	将 0 一并参与随机列表	安全输入
secureMode	Boolean	false	支付密码布局占位策略	密码输入
title	String	''	顶部标题	键盘说明
subtitle	String	''	标题下方辅助文案。	安全输入、金额规则等短提示。
showCloseIcon	Boolean	false	显示标题栏关闭图标	显式关闭
displayMode	String	'sheet'	sheet/card/dialog/popup	容器形态
safeAreaInsetBottom	Boolean	true	底部安全区	移动端
zIndex	Number	100	宿主层级	多浮层
showTrigger	Boolean	false	显示内置触发器	字段式输入
triggerPlaceholder	String	''	触发器占位文案	内置触发器
triggerLabel	String	''	触发器标签	内置触发器
triggerDisabled	Boolean	false	禁用触发器	内置触发器
triggerStyle	String | Object	''	触发器样式	样式覆盖
targetFocus	Boolean	false	外部输入目标焦点状态	联动输入框
customClass	String	''	键盘类名	样式覆盖
customStyle	String | Object	''	键盘样式	样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
update:modelValue / input	输入值变化	(value: String)	新输入值
update:show	请求开关键盘	(show: Boolean)	显示状态
update:targetFocus	键盘开关同步焦点	(focused: Boolean)	焦点状态
delete	点击删除	()	删除后触发
close / blur	关闭或失焦	()	不区分来源
confirm	点击完成	(value: String)	当前值
complete	达到 maxlength	(value: String)	完整值
trigger-click	点击触发器	()	打开前触发
open	调用打开	()	键盘打开
target-focus / target-blur	同步目标焦点	()	焦点变化
switch	点击省份键盘的 abc 或字母键盘的“省份”操作键	(target: String)	组件内部会切换省份/字母布局，同时传出 'alphabet' 或 'province' 方便业务记录状态。

事件使用示例

<template>
  <xtf-number-keyboard
    v-model="code"
    v-model:show="show"
    :maxlength="4"
    @input="log"
    @complete="complete"
    @confirm="confirm"
    @close="logClose"
  />
</template>
<script>
export default {
  data() {
    return { show: true, code: '' }
  },
  methods: {
    log(v) {
      console.log('input', v)
    },
    complete(v) {
      console.log('complete', v)
    },
    confirm(v) {
      console.log('confirm', v)
    },
    logClose() {
      console.log('close')
    }
  }
}
</script>

---

方法

1. open() - 打开键盘

返回值：void。

this.$refs.keyboard.open()

---

插槽

插槽名	作用域参数	说明
trigger	value: String、openKeyboard: Function	替换 showTrigger 显示的内置触发器。调用 openKeyboard() 会触发 trigger-click 并请求打开键盘。

trigger 插槽示例

<template>
  <xtf-number-keyboard
    v-model="amount"
    v-model:show="show"
    show-trigger
    extra-key="."
    @confirm="confirm"
  >
    <template #trigger="{ value, openKeyboard }">
      <view class="amount-field" @tap="openKeyboard">
        <text>付款金额</text>
        <text>{{ value || '点击输入' }}</text>
      </view>
    </template>
  </xtf-number-keyboard>
</template>
<script>
export default {
  data() {
    return { amount: '', show: false }
  },
  methods: {
    confirm(value) {
      console.log('confirm', value)
    }
  }
}
</script>

---

主题说明

• 背景和按键使用 --xtf-number-keyboard-bg、--xtf-number-keyboard-key-bg。
• 完成键使用 --xtf-number-keyboard-close-bg，删除键使用 --xtf-number-keyboard-delete-bg。
• soft、card、contrast 内置完整色板，custom 直接继承全局主题变量。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。