前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载导读本文围绕 wot-design-uni 组件库中的wd-keyboard虚拟键盘组件展开系统讲解其三种核心模式默认数字键盘、带右侧栏的金额键盘、车牌号键盘以及v-model双向绑定、extra-key额外按键、随机键序、蒙层遮罩控制等实战用法。读完本文你将能够基于 keyboard.md 官方文档与组件源码在 uni-app 项目中快速搭建数字输入、密码输入、身份证号输入和车牌号录入等场景的完整交互方案并理解其底层按键生成与事件分发机制。wd-keyboard是 wot-design-uni 提供的一款底部弹出的虚拟键盘组件官方定位为「用于输入数字、密码、身份证或车牌号等场景」组件源码位于 wd-keyboard.vue其按键单元由 key/index.vue 实现对外行为均有对应单元测试覆盖见 wd-keyboard.test.ts。一、组件概览与快速上手1.1 组件定位与适用场景wd-keyboard是一个基于wd-popup底部弹层封装的虚拟数字键盘组件结构上完全复用了 wd-popup 的弹层能力positionbottom底部弹出、遮罩、滚动锁定、安全区适配等因此它天然具备底部滑出动画与蒙层遮罩zIndex层级控制与root-portal脱离页面解决 fixed 失效lockScroll背景滚动锁定与safeAreaInsetBottom底部安全区适配。从源码keyboardProps见 types.ts可以看到组件对外暴露约 20 个属性核心能力集中在mode三种键盘模式、extraKey额外按键、carLang/autoSwitchLang车牌键盘语言控制三大维度。1.2 最小可用示例键盘的展示与关闭通过v-model:visible控制配合wd-cell点击唤起是最典型的组合方式wd-cell title默认键盘 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible inputonInput deleteonDelete/wd-keyboardconst { show: showToast } useToast() const visible refboolean(false) function showKeyBoard() { visible.value true } const onInput (value) showToast(${value}) const onDelete () showToast(删除)要点说明visible使用refboolean维护点击wd-cell时置为true唤起键盘input事件在点击数字/字母按键时触发携带按键文本delete事件在点击删除键时触发组件内部通过emit(update:visible, false)在关闭时回写状态见源码handleClose实现受控关闭。二、三种键盘模式default / custom / carmode属性是wd-keyboard最核心的开关源码中定义为type KeyboardMode default | custom | car默认值default。三种模式对应三类典型业务场景mode 取值键盘形态典型场景default1~9 额外键 0 删除键共 12 键通用数字/密码输入custom主键区 右侧栏删除 完成按钮金额、小数输入car车牌号键盘省份/字母双面板车牌号录入组件模板中按mode分别渲染两种结构见 wd-keyboard.vuemode ! car时渲染.wd-keyboard__body键区 可选的右侧栏mode car时渲染独立的.wd-keyboard-car__body车牌键区。按键数组由keys计算属性生成computed内部根据模式分发到三个生成函数const keys computed(() props.mode ! car ? props.mode custom ? genCustomKeys() : genDefaultKeys() : genCarKeys() )下面逐一展开每种模式的配置细节。三、默认数字键盘与extra-key额外按键3.1 基本用法不传mode即为默认数字键盘1~9 排成三行底部一行由「额外键 0 删除键」组成。单元测试基本渲染断言默认模式下共渲染 12 个按键见 wd-keyboard.test.ts与源码genDefaultKeys的生成逻辑一致function genDefaultKeys(): Key[] { return [ ...genBasicKeys(), // 1~9 { text: props.extraKey as string, type: extra }, // 左下角额外键 { text: 0 }, { text: props.showDeleteKey ? props.deleteText : , type: props.showDeleteKey ? delete : } ] }3.2 身份证键盘extra-keyXextra-key用于自定义左下角按键内容。以身份证输入场景为例身份证号末尾可能是数字或大写X将extra-key设为X即可wd-cell title身份证键盘 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible extra-keyX close-text完成 inputonInput deleteonDelete /此时键盘布局为1~9 X 0 删除键。extra-key的类型为string | string[]见 types.ts单个字符串渲染一个额外键数组形式可渲染多个详见下文「多个额外按键」。3.3 关于close-text的显示逻辑细心的读者会发现上面的示例都传了close-text完成。这是因为源码中的showClose计算属性规定只有mode为default或car时头部才会渲染关闭按钮const showClose computed(() { return props.closeText (props.mode default || props.mode car) })custom模式下完成按钮不显示在头部而是作为右侧栏底部的一个大按钮渲染见模板wd-keyboard__sidebar。同时showHeader由「有标题或有关闭按钮」共同决定const showHeader computed(() { return showTitle.value || showClose.value })四、带右侧栏的键盘modecustom金额输入场景设置modecustom后键盘左侧是数字主键区右侧出现竖排侧栏侧栏包含删除键与「完成」按钮——非常适合金额、小数等需要明确「确认提交」的输入场景wd-cell title带右侧栏的键盘 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible modecustom extra-key. close-text完成 inputonInput deleteonDelete /wd-keyboard4.1 单个额外按键的布局当extra-key为单个字符串时源码genCustomKeys会生成「数字 0占双倍宽度 额外键」的特殊布局function genCustomKeys(): Key[] { const keys genBasicKeys() const extraKeys Array.isArray(props.extraKey) ? props.extraKey : [props.extraKey] if (extraKeys.length 1) { // 只有一个额外按键0 键加宽额外键占一格 keys.push({ text: 0, wider: true }, { text: extraKeys[0], type: extra }) } else if (extraKeys.length 2) { // 两个额外按键额外键 0 额外键 keys.push({ text: extraKeys[0], type: extra }, { text: 0 }, { text: extraKeys[1], type: extra }) } return keys }传入extra-key.后主键区底部为「加宽的 0 小数点」配合右侧栏的删除与完成按钮即构成一个标准的金额录入键盘。单元测试自定义模式 - 单个额外按键断言此时共 13 个按键9 数字 0 额外键 侧栏删除键完成键不计数于WdKey组件统计口径之外。4.2 两个额外按键数组形式当mode为custom时extra-key支持传入字符串数组例如[00, .]可以同时提供「快速输入 00」和「小数点」两个按键wd-cell title多个额外按键 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible modecustom :extra-key[00, .] close-text完成 inputonInput deleteonDelete /布局为1~9 00 0 .加上右侧栏共 14 个按键测试自定义模式 - 两个额外按键对此做了断言见 wd-keyboard.test.ts。五、车牌号键盘modecar与语言切换机制5.1 基础用法将mode设置为car即进入车牌号键盘。它是一款双面板键盘初始展示「中文省份简称面板」点击切换键后进入「数字 字母面板」wd-cell title车牌号键盘 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible modecar inputonInput deleteonDelete/wd-keyboard5.2 键盘内容与排布源码级车牌键盘的面板数据定义在 constants.ts省份面板CAR_KEYBOARD_AREAS包含 36 个字符除 31 个省级行政区简称外还收录了「挂、使、学、港、澳」等特殊/特定用途前缀字符字母数字面板CAR_KEYBOARD_KEYS包含 0~9 十个数字以及去除I、O两个字母后的 24 个大写字母依据车牌规则不使用这两个字母。genCarKeys与splitCarKeys的生成逻辑为取当前语言对应的 36 个按键前 30 个渲染在第一屏剩余 6 个与「切换键 删除键」一起渲染在第二屏切换键文本随语言变化中文态显示ABC英文态显示省份删除键为加宽双倍宽度function genCarKeys(): ArrayKey { const [keys, remainKeys] splitCarKeys() return [ ...keys, { text: carKeyboardLang.value zh ? ABC : 省份, type: extra, wider: true }, ...remainKeys, { text: props.deleteText, type: delete, wider: true } ] }单元测试车牌模式的注释精确描述了两种面板的按键总数中文态 38 键36 省份 ABC 删除英文态 36 键10 数字 24 字母 省份 删除即expect(keys.length).toBe(38)见 wd-keyboard.test.ts。5.3 车牌键盘语言控制car-lang与auto-switch-lang车牌键盘支持中文省份zh与英文字母en两种语言模式通过car-lang控制auto-switch-lang则控制是否自动切换语言版本 1.13.0 起支持。受控模式手动控制语言切换!-- 受控模式手动控制语言切换 -- wd-cell title车牌号键盘受控 :valuevalue is-link clickshowKeyBoard / wd-keyboard v-modelvalue v-model:visiblevisible v-model:car-langlang modecar inputonInput deleteonDelete /wd-keyboardconst visible refboolean(false) const value refstring() const lang refzh | en(zh)非受控模式禁用自动切换!-- 非受控模式禁用自动切换 -- wd-cell title车牌号键盘非受控 :valuevalue2 is-link clickshowKeyBoard2 / wd-keyboard v-modelvalue2 v-model:visiblevisible2 modecar auto-switch-lang inputonInput deleteonDelete /wd-keyboardconst visible2 refboolean(false) const value2 refstring()两种模式的区别在源码中有清晰的分支处理handlePress内点击切换键文本为ABC或省份时若外部传入了car-lang受控组件emit(update:carLang, newLang)交由父级更新否则非受控内部维护carKeyboardLang完成切换auto-switch-lang自动切换逻辑非受控时生效输入第一位省份简称后自动将键盘切到英文态if (props.mode car newValue.length 1 props.autoSwitchLang) carKeyboardLang.value en删除键将内容删空后自动切回中文省份态if (props.mode car newValue.length 0 props.autoSwitchLang) carKeyboardLang.value zh。语言状态通过computed桥接受控与非受控两种数据流const carKeyboardLang computed({ get: () (props.carLang ? props.carLang : carLang.value), set: (value: CarKeyboardLang) { carLang.value value } })演示页 keyboard/Index.vue 中同时展示了「auto-switch-lang非受控」与「v-model:car-lang受控」两种用法可作为参考实现。六、标题title属性与#title插槽6.1title属性通过title属性可以设置键盘顶部标题常用于「输入密码」等需要明确语义的场景wd-cell title带标题的键盘 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible title输入密码 extra-key. close-text完成 inputonInput deleteonDelete /标题的显示由showTitle计算属性控制只要传入title或存在title插槽内容就渲染标题区域。默认渲染在头部居中位置源码通过title-left修饰类支持标题左对齐的扩展。6.2 使用 slot 自定义标题当需要富样式标题如彩色文字、图标 文案组合时使用#title插槽完全接管标题渲染wd-cell title使用 slot 自定义标题 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible extra-key. close-text完成 inputonInput deleteonDelete template #title text stylecolor: red自定义标题/text /template /wd-keyboard插槽内容会覆盖默认的title文本渲染见模板v-ifshowTitle分支。单元测试使用插槽自定义标题验证了插槽内容能正确渲染到.custom-title节点见 wd-keyboard.test.ts。七、随机数字键盘random-key-order支付密码、验证码等安全等级较高的场景可以开启random-key-order让数字键每次弹出时随机排序防止按键位置被窥探记忆wd-cell title随机数字键盘 is-link clickshowKeyBoard / wd-keyboard v-model:visiblevisible random-key-order inputonInput deleteonDelete /其底层实现是genBasicKeys在生成 1~9 后调用shuffleArray进行 Fisher–Yates 洗牌function shuffleArrayT(arr: T[]): T[] { const newArr [...arr] for (let i newArr.length - 1; i 0; i--) { const j Math.floor(Math.random() * (i 1)) ;[newArr[i], newArr[j]] [newArr[j], newArr[i]] } return newArr }该算法原地交换、时间复杂度 O(n)且每次渲染都会重新随机。单元测试随机键盘顺序通过 mockMath.random验证了该属性开关见 wd-keyboard.test.ts。需要注意的是随机化仅作用于 1~9 数字键extra-key、0、删除键的位置保持固定。八、双向绑定v-model与maxlength8.1 绑定输入值键盘不仅可以通过事件向上抛值还支持v-model直接绑定当前输入值并同步展示在wd-cell上wd-cell title双向绑定 :valuevalue1 is-link clickshowKeyBoard / wd-keyboard v-modelvalue1 :maxlength6 v-model:visiblevisible title键盘标题 extra-key. close-text完成 inputonInput deleteonDelete /wd-keyboardconst visible refboolean(false) const value1 refstring()8.2 输入/删除的内部数据流从源码handlePress可以看到每次按键都同步触发两件事const value props.modelValue if (type delete) { emit(delete) const newValue value.slice(0, value.length - 1) emit(update:modelValue, newValue) // ...车牌键盘删空后切回中文 } else if (type close) { handleClose() } else if (value.length props.maxlength) { emit(input, text) const newValue value text emit(update:modelValue, newValue) // ...车牌键盘首位输入后切英文 }输入value.length maxlength时先emit(input, text)抛原始按键文本再emit(update:modelValue, value text)驱动v-model更新删除emit(delete)后通过value.slice(0, -1)截断一位并回写modelValue长度限制maxlength默认Infinity一旦达到上限后续按键直接不响应单元测试最大长度限制验证了这一点见 wd-keyboard.test.ts。值得注意maxlength同时是键盘输入与外部赋值之间的唯一长度闸口若外部直接修改modelValue超出长度需自行约束。九、蒙层遮罩控制modal与hide-on-click-outside9.1 两个属性的分工wd-keyboard将「是否有遮罩」与「遮罩是否透明」拆成了两个独立开关属性作用默认值hideOnClickOutside是否显示蒙层遮罩有遮罩时点击遮罩可关闭键盘truemodal遮罩是否透明true为正常不透明遮罩false为透明遮罩false对应模板中的透传写法见 wd-keyboard.vuewd-popup v-modelshow positionbottom :modal-stylemodal ? : opacity: 0; :modalhideOnClickOutside click-modalhandleClose 也就是说键盘组件的hideOnClickOutside直接映射为wd-popup的modal决定弹层是否有遮罩层键盘组件的modal则通过modal-style控制遮罩的透明度——false时遮罩为opacity: 0的透明层视觉上无遮挡、但仍能拦截点击true时显示正常半透明遮罩。9.2 两种使用姿势开启遮罩 点击外部关闭默认能力wd-cell title双向绑定 :valuevalue1 is-link clickshowKeyBoard / wd-keyboard :modaltrue :hide-on-click-outsidetrue v-model:visiblevisible inputonInput deleteonDelete /关闭遮罩 手动控制收起更灵活官方文档给出的建议是当存在遮罩时键盘展开后必须先点击遮罩关闭键盘才能继续操作页面其他按钮如果希望「点击外部任意区域即收起」的体验更自由可以关闭hide-on-click-outside改为完全手动控制visible的展示与收起。::: tip 提示modal仅控制遮罩是否为透明hideOnClickOutside控制弹窗是否有遮罩。当存在遮罩时点击遮罩即可关闭键盘但键盘展开时必须先点击遮罩关闭当前键盘后才可点击其他按钮也可以关闭hideOnClickOutside手动控制键盘展示状态来实现更灵活的点击外部收起。 :::9.3 背景滚动锁定lockScroll默认true用于锁定背景滚动。需要注意文档中的明确说明锁定时蒙层里的内容也将无法滚动。如果键盘内部或其下层有需要滚动的区域应谨慎关闭该属性如设为false。十、组件 API 完整参考10.1 Attributes参数说明类型可选值默认值最低版本v-model:visible是否展开boolean-false1.3.10v-model绑定的值string--1.3.10title标题string--1.3.10mode键盘模式stringdefault,car,customdefault1.3.10zIndex层级number-1001.3.10maxlength最大长度number-Infinity1.3.10showDeleteKey是否显示删除键boolean-true1.3.10randomKeyOrder是否随机键盘按键顺序boolean-false1.3.10closeText确认按钮文本string--1.3.10deleteText删除按钮文本string--1.3.10closeButtonLoading关闭按钮是否显示加载状态boolean-false1.3.10modal是否显示蒙层遮罩boolean-false1.3.10hideOnClickOutside是否在点击外部时收起键盘boolean-true1.3.10lockScroll是否锁定背景滚动锁定时蒙层里的内容也将无法滚动boolean-true1.3.10safeAreaInsetBottom是否在底部安全区域内boolean-true1.3.10extraKey额外按键string/string[]--1.3.10root-portal是否从页面中脱离出来用于解决各种 fixed 失效问题boolean-false1.11.0v-model:carLang车牌键盘语言模式当modecar时生效stringzh,en-1.13.0autoSwitchLang是否自动切换车牌键盘语言当modecar且car-lang是非受控状态时生效boolean-false1.13.0源码层面的补充说明zIndex默认100会透传给底层wd-popup其自身默认10用于控制键盘相对其他弹层的层级rootPortal在三种运行环境下实现方式不同源码注释标注H5 端teleport、APP 端renderjs、小程序端root-portal用于解决各种fixed定位失效问题closeButtonLoading会传递给右侧栏「完成」键配合wd-loading渲染加载态适合提交校验等异步场景见 key/index.vue。10.2 Slotname说明类型最低版本title标题-1.2.1210.3 Events事件名称说明参数最低版本input点击按键时触发key: string-delete点击删除键时触发--close点击关闭按钮或非键盘区域时触发--三个事件与v-model的联动已在源码handlePress中体现input抛按键文本、delete通知删除动作、close触发后同时emit(update:visible, false)收起键盘。10.4 外部样式类类名说明最低版本custom-class根节点样式类1.3.10custom-style根节点样式1.3.10十一、按键单元与交互细节源码实现11.1wd-key按键单元每个按键由内部wd-key组件渲染key/index.vue其行为特征触摸反馈通过useTouch组合式函数监听touchstart / touchmove / touchend按下时置active状态触发按压高亮若触摸过程中发生明显位移touch.direction有值则取消激活避免误触按键类型渲染type属性delete优先显示deleteText自定义文本未传时回退为内置keyboard-delete图标extra优先显示按键文本未传时回退为keyboard-collapse收起图标close显示完成文本并可叠加loading加载态宽高控制wider使按键占 2 个标准键宽度flex-basis: 66%large使侧栏按键纵向撑满见 key/index.scss。11.2 空文本extra键的隐藏行为handlePress中有一段特殊处理当extra类型按键文本为空字符串时直接调用handleClose()收起键盘if (type extra) { if (text ) { return handleClose() } else if (text ABC || text 省份) { // 车牌键盘语言切换 } }这意味着「不传extra-key的default模式」在默认键盘里左下角会是一个空按键点击它等同于点击收起/关闭——这与key/index.vue中extra类型空文本渲染keyboard-collapse图标的逻辑相互印证。十二、样式定制与暗黑模式12.1 基于 CSS 变量的主题定制键盘的视觉样式全部通过 variable.scss 中定义的 CSS 变量驱动支持在业务项目中按需覆写CSS 变量默认值作用--wot-keyboard-key-height48px按键高度--wot-keyboard-key-font-size28px按键字号--wot-keyboard-key-background#ffffff按键背景色--wot-keyboard-key-border-radius8px按键圆角--wot-keyboard-delete-font-size16px删除键字号--wot-keyboard-key-active-color灰色系按键按压色--wot-keyboard-button-text-color#ffffff完成按钮文字色--wot-keyboard-button-background主题色完成按钮背景色--wot-keyboard-button-active-opacity0.6完成按钮按压透明度--wot-keyboard-background灰色系键盘面板背景色--wot-keyboard-title-height34px标题区高度--wot-keyboard-title-color深灰色标题文字色--wot-keyboard-title-font-size16px标题字号--wot-keyboard-close-color主题色关闭按钮文字色--wot-keyboard-close-font-size14px关闭按钮字号--wot-keyboard-icon-size22px内置图标尺寸12.2 暗黑模式适配组件内置了.wot-theme-dark暗黑模式样式见 index.scss键盘面板使用--dark-background5、标题使用--dark-color按键单元则使用--dark-background2/--dark-background4处理普通态与按压态见 key/index.scss。开启暗黑模式时无需额外配置。十三、验证与测试组件行为由 Vitest 单元测试完整覆盖wd-keyboard.test.ts主要用例包括基本渲染与默认模式 12 键布局title属性与#title插槽渲染visible显隐状态与wd-popup联动按键点击触发input与update:modelValue删除键触发delete并截断modelValue关闭按钮触发close与update:visiblemaxlength长度上限拦截custom模式 1 个 / 2 个额外按键的布局数量car模式 38 键布局randomKeyOrder开关双向绑定模拟触摸输入 删除点击遮罩关闭键盘。这些测试同时是理解组件内部数据流press→handlePress→emit的最佳阅读材料。十四、常见问题与最佳实践键盘被遮挡 / fixed 失效在复杂弹层或 webview 场景下若键盘定位异常设置root-portal为true使其脱离页面容器。车牌键盘语言状态不同步受控模式请务必使用v-model:car-lang绑定并维护lang状态非受控模式可放心开启auto-switch-lang组件会自动在「输入省份后切英文、删空后切回中文」。金额输入的小数点约束modecustomextra-key.只负责提供按键小数点去重、金额格式校验需在input回调中自行处理。安全场景密码 / 验证码键盘请开启random-key-order并配合maxlength限制长度。自定义视觉优先通过--wot-keyboard-*CSS 变量调整主题避免直接覆写内部 class 导致升级冲突局部微调可使用custom-class/custom-style外部样式类。十五、总结wd-keyboard以「一个组件、三种模式」覆盖了移动端绝大多数的定制键盘需求default应对通用数字与密码输入custom通过右侧栏与多额外键应对金额类场景car双面板设计完整贴合车牌号录入规则省份前缀 去除 I/O 的字母数字。配合v-model双向绑定、maxlength、random-key-order、蒙层遮罩控制与完整的 CSS 变量主题体系开发者可以在不引入原生键盘的前提下构建安全、规范且体验统一的虚拟输入方案。更多演示代码可参考 keyboard/Index.vue英文版文档见 en-US/component/keyboard.md。赞分享前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载相关推荐从 10 分钟录音到能用的音色RVC 语音克隆实操走一遍从 10 分钟录音到能用的音色RVC 语音克隆实操走一遍 它到底在解决什么问题 RVC 语音克隆要解决的问题很直接拿一段 10 分钟左右的录音就能把 A人工智能AI 应用语音音频深度学习uni-app X 软键盘控制实战uni-keyboard 插件 hideKeyboard 与键盘高度监听全解析uni app X 软键盘控制实战uni keyboard 插件 hideKeyboard 与键盘高度监听全解析 导读 本文围绕开源仓库 gh_mirrors示例工程前端移动开发跨平台ant-design-mobile NumberKeyboard 数字键盘组件完全指南属性、自定义键位与 VirtualInput 联动ant design mobile NumberKeyboard 数字键盘组件完全指南属性、自定义键位与 VirtualInput 联动 数字键盘NumbeUI组件前端移动开发上一篇3步搞定B站4K视频免费下载下一篇5大平台一次打通MediaCrawler用浏览器上下文保留让多平台数据采集告别JS逆向创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考