BizAmountKeyboard 金额数字键盘

金额数字键盘：显示区实时千分位预览（空时 0.00 灰字占位）+ 右侧「清空」；4 列键盘（1-9 / . / 0 / 00 / 退格 / 清空 / 确认跨两行）。严格输入规则：前导 0 唯一（0 后只能输 .）、小数点唯一、小数位满 decimal-length 追加忽略、整数位达 integer-limit 截断 + error + 抖动、00 键超限截断；max-amount 输入中超限红字提示、确认时抖动拦截。支持 inline 直接渲染 / popup 底部弹层（Teleport + slide-up）、random-keys 数字乱序防偷窥。收银台、转账金额录入、POS 收款等触屏场景。

基础用法

金额输入

0.00元

原始值（v-model）：（空）（非千分位，如 1234.5）

inline 模式直接渲染；v-model 为金额原始字符串（非千分位），显示区实时千分位预览。

<script setup lang="ts">
/** 场景：基础——inline 模式，千分位实时预览 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'

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

<template>
  <div>
    <BizAmountKeyboard v-model="amount" style="max-width: 360px" />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      原始值（v-model）：{{ amount === '' ? '（空）' : amount }}（非千分位，如 1234.5）
    </p>
  </div>
</template>

显示代码

底部弹层

已录入金额：（空）

mode="popup" 时 Teleport 到 body 的 fixed 底部弹层，v-model:visible 控制开合；确认或点击遮罩关闭，每次打开重洗乱序键盘。

<script setup lang="ts">
/** 场景：popup 底部弹层——v-model:visible 开合，确认/遮罩关闭 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'

const visible = ref(false)
const amount = ref('')
</script>

<template>
  <div>
    <el-button type="primary" @click="visible = true">打开金额键盘</el-button>
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      已录入金额：{{ amount === '' ? '（空）' : `${amount} 元` }}
    </p>
    <BizAmountKeyboard v-model="amount" v-model:visible="visible" mode="popup" title="请输入收款金额" />
  </div>
</template>

显示代码

乱序防偷窥

金额输入

0.00元

数字 1-9 位置随机洗牌（0 / 00 / . 固定）；popup 模式下每次打开弹层还会重新洗牌。

random-keys 开启后数字 1-9 位置洗牌（0 / 00 / . 固定），防止旁人记忆按键位置推算金额。

<script setup lang="ts">
/** 场景：乱序防偷窥——random-keys 数字 1-9 洗牌 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'

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

<template>
  <div>
    <BizAmountKeyboard v-model="amount" random-keys style="max-width: 360px" />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      数字 1-9 位置随机洗牌（0 / 00 / . 固定）；popup 模式下每次打开弹层还会重新洗牌。
    </p>
  </div>
</template>

显示代码

输入校验

金额输入

0.00元

整数位上限 5 位：第 6 位数字被截断并抖动；金额上限 99,999 元：输入中超限红字提示，确认时抖动拦截。
最近一次 error：（无）
确认结果：（未确认）

integer-limit 整数位上限（超限截断 + 抖动 + error）与 max-amount 金额上限（输入中红字提示、确认拦截）。

<script setup lang="ts">
/** 场景：输入校验——integer-limit 截断抖动 + max-amount 上限拦截 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'
import type { BizAmountKeyboardError } from 'vue3-ep-biz-lib'

const amount = ref('')
const lastError = ref<BizAmountKeyboardError | null>(null)
const confirmed = ref('')

const onError = (err: BizAmountKeyboardError): void => {
  lastError.value = err
}

const onConfirm = (value: string): void => {
  confirmed.value = value
}
</script>

<template>
  <div>
    <BizAmountKeyboard
      v-model="amount"
      :integer-limit="5"
      :max-amount="99999"
      style="max-width: 360px"
      @error="onError"
      @confirm="onConfirm"
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary); line-height: 1.8">
      整数位上限 5 位：第 6 位数字被截断并抖动；金额上限 99,999 元：输入中超限红字提示，确认时抖动拦截。<br />
      最近一次 error：{{ lastError === null ? '（无）' : `${lastError.type}｜${lastError.message}` }}<br />
      确认结果：{{ confirmed === '' ? '（未确认）' : `${confirmed} 元` }}
    </p>
  </div>
</template>

显示代码

小数位数

0 位小数（「.」键禁用）：（空）

金额输入

0元

1 位小数：（空）

金额输入

0.0元

3 位小数：（空）

金额输入

0.000元

decimal-length 支持 0~3 位小数：0 位时 . 键禁用，空占位分别为 0 / 0.0 / 0.000。

<script setup lang="ts">
/** 场景：小数位数——decimal-length 0/1/3 位对比 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'

const a = ref('')
const b = ref('')
const c = ref('')
</script>

<template>
  <div>
    <el-space direction="vertical" alignment="flex-start" :size="14">
      <div>
        <p style="margin: 0 0 4px; font-size: 12px; color: var(--el-text-color-secondary)">
          0 位小数（「.」键禁用）：{{ a === '' ? '（空）' : a }}
        </p>
        <BizAmountKeyboard v-model="a" :decimal-length="0" style="max-width: 320px" />
      </div>
      <div>
        <p style="margin: 0 0 4px; font-size: 12px; color: var(--el-text-color-secondary)">
          1 位小数：{{ b === '' ? '（空）' : b }}
        </p>
        <BizAmountKeyboard v-model="b" :decimal-length="1" style="max-width: 320px" />
      </div>
      <div>
        <p style="margin: 0 0 4px; font-size: 12px; color: var(--el-text-color-secondary)">
          3 位小数：{{ c === '' ? '（空）' : c }}
        </p>
        <BizAmountKeyboard v-model="c" :decimal-length="3" style="max-width: 320px" />
      </div>
    </el-space>
  </div>
</template>

显示代码

素色主题

金额输入

0.00元

plain 主题：白底描边按键，悬浮主题色描边，适配浅色表单内嵌场景；当前值：（空）

theme="plain" 白底描边按键，适配浅色表单内嵌场景。

<script setup lang="ts">
/** 场景：主题——plain 素色描边 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'

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

<template>
  <div>
    <BizAmountKeyboard v-model="amount" theme="plain" style="max-width: 360px" />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      plain 主题：白底描边按键，悬浮主题色描边，适配浅色表单内嵌场景；当前值：{{
        amount === '' ? '（空）' : amount
      }}
    </p>
  </div>
</template>

显示代码

自定义显示区

金额输入

充值金额0.00CNY

toolbar 插槽：单笔充值限额 50,000 元，请核对后确认

display 插槽替换金额显示区（作用域参数 amount 原始值 / display 千分位文本 / over-limit 超限标记）。

<script setup lang="ts">
/** 场景：自定义显示区——display 插槽替换金额展示 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'

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

<template>
  <div>
    <BizAmountKeyboard v-model="amount" style="max-width: 360px">
      <template #display="{ amount: raw, display, overLimit }">
        <div
          style="
            display: flex;
            align-items: baseline;
            gap: 6px;
            min-height: 42px;
            padding: 4px 10px;
            border-radius: var(--el-border-radius-base);
            background-color: var(--el-fill-color-light);
            box-sizing: border-box;
            width: 100%;
          "
        >
          <span style="font-size: 13px; color: var(--el-text-color-secondary)">充值金额</span>
          <span
            :style="{
              flex: 1,
              textAlign: 'right',
              fontSize: '22px',
              fontWeight: 600,
              color: overLimit ? 'var(--el-color-danger)' : 'var(--el-text-color-primary)',
            }"
          >
            {{ raw === '' ? '0.00' : display }}
          </span>
          <span style="font-size: 13px; color: var(--el-text-color-secondary)">CNY</span>
        </div>
      </template>
      <template #toolbar>
        <p style="margin: 8px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
          toolbar 插槽：单笔充值限额 50,000 元，请核对后确认
        </p>
      </template>
    </BizAmountKeyboard>
  </div>
</template>

显示代码

事件

金额输入

0.00元

input 轨迹（最近 8 次）：（无）
confirm：（未确认）
最近一次 error：（无）

input 每次输入变化（原始字符串）、confirm 确认、error 校验错误（integer-limit / decimal-limit / max-amount）回显。

<script setup lang="ts">
/** 场景：事件——input / confirm / error 回显 */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'
import type { BizAmountKeyboardError } from 'vue3-ep-biz-lib'

const amount = ref('')
const inputLog = ref<string[]>([])
const confirmed = ref('')
const lastError = ref<BizAmountKeyboardError | null>(null)

const onInput = (value: string): void => {
  inputLog.value = [...inputLog.value, value].slice(-8)
}

const onConfirm = (value: string): void => {
  confirmed.value = value
}

const onError = (err: BizAmountKeyboardError): void => {
  lastError.value = err
}
</script>

<template>
  <div>
    <BizAmountKeyboard
      v-model="amount"
      :decimal-length="2"
      style="max-width: 360px"
      @input="onInput"
      @confirm="onConfirm"
      @error="onError"
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary); line-height: 1.8">
      input 轨迹（最近 8 次）：{{ inputLog.length === 0 ? '（无）' : inputLog.join(' → ') }}<br />
      confirm：{{ confirmed === '' ? '（未确认）' : `${confirmed} 元` }}<br />
      最近一次 error：{{ lastError === null ? '（无）' : `${lastError.type}｜${lastError.message}` }}
    </p>
  </div>
</template>

显示代码

自定义文案

转入金额（元）

0.00元

title「转入金额（元）」、确认键文案「下一步」；当前值：（空）

title 标题与 confirm-text 确认键文案自定义。

<script setup lang="ts">
/** 场景：自定义文案——title / confirm-text */
import { ref } from 'vue'
import { BizAmountKeyboard } from 'vue3-ep-biz-lib'

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

<template>
  <div>
    <BizAmountKeyboard
      v-model="amount"
      title="转入金额（元）"
      confirm-text="下一步"
      style="max-width: 360px"
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      title「转入金额（元）」、确认键文案「下一步」；当前值：{{ amount === '' ? '（空）' : amount }}
    </p>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
v-model	string | number	''	金额原始字符串（非千分位，如 '1234.5'）
mode	'inline' | 'popup'	'inline'	展示模式：直接渲染 / 底部弹层
v-model:visible	boolean	false	popup 模式弹层开关
title	string	'金额输入'	标题（popup 头部 / inline 标签行）
decimal-length	number	2	小数位数 0~3；0 时 . 键禁用
integer-limit	number	7	整数位上限；超限截断 + error + 抖动
max-amount	number	—	金额上限（元）；确认超限拦截
random-keys	boolean	false	数字 1-9 乱序（防偷窥）
theme	'default' | 'plain'	'default'	素色描边主题
confirm-text	string	'确认'	确认键文案
disabled	boolean	false	禁用全部按键

Events

事件名	参数	说明
update:modelValue	(value: string)	金额变化（原始字符串）
input	(value: string)	每次输入变化（原始字符串，非千分位）
confirm	(value: string)	确认（超限时拦截不触发）
error	(err: { type: 'integer-limit' | 'decimal-limit' | 'max-amount'; message: string })	校验错误
update:visible	(value: boolean)	popup 弹层开关变化

Slots

插槽名	参数	说明
display	{ amount: string, display: string, overLimit: boolean }	替换金额显示区
toolbar	—	键盘下方扩展条

Expose

名称	类型	说明
open / close	() => void	popup 弹层开合控制
clear	() => void	清空当前金额
getValue	() => string	取当前金额原始字符串（非千分位）