Skip to content

Commit 59df1b7

Browse files
RYGRITRYGRIT
authored
feat: ✨ 新增Keyboard虚拟键盘支持车牌号输入 (#567)
* feat: ✨ Keyboard 虚拟键盘支持输入车牌号(#351) * docs: ✏️ 虚拟键盘支持车牌号输入
1 parent feb64ea commit 59df1b7

File tree

13 files changed

+1037
-34
lines changed

13 files changed

+1037
-34
lines changed

‎docs/.vitepress/config.mts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,9 @@ export default defineConfig({
368368
}, {
369369
link: "/component/count-to",
370370
text: "CountTo 数字滚动"
371+
}, {
372+
link: "/component/keyboard",
373+
text: "Keyboard 虚拟键盘"
371374
}, {
372375
link: "/component/number-keyboard",
373376
text: "NumberKeyboard 数字键盘"

‎docs/component/keyboard.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
<frame/>
2+
3+
# Keyboard 虚拟键盘
4+
5+
虚拟数字键盘，用于输入数字、密码、身份证或车牌号等场景。
6+
7+
## 基本用法
8+
9+
可以通过 `v-model:visible` 控制键盘是否展示。
10+
11+
```html
12+
<wd-cell title="默认键盘" is-link @click="showKeyBoard" />
13+
14+
<wd-keyboard v-model:visible="visible" @input="onInput" @delete="onDelete"></wd-keyboard>
15+
```
16+
17+
```ts
18+
const { show: showToast } = useToast()
19+
const visible = ref<boolean>(false)
20+
21+
function showKeyBoard() {
22+
visible.value = true
23+
}
24+
25+
const onInput = (value) => showToast(`${value}`)
26+
const onDelete = () => showToast('删除')
27+
```
28+
29+
## 带右侧栏的键盘
30+
31+
将 `mode` 属性设置为 `custom` 来展示键盘的右侧栏，常用于输入金额的场景。
32+
33+
```html
34+
<wd-cell title="带右侧栏的键盘" is-link @click="showKeyBoard" />
35+
36+
<wd-keyboard v-model:visible="visible" mode="custom" extra-key="." close-text="完成" @input="onInput" @delete="onDelete"></wd-keyboard>
37+
```
38+
39+
```ts
40+
const { show: showToast } = useToast()
41+
const visible = ref<boolean>(false)
42+
43+
function showKeyBoard() {
44+
visible.value = true
45+
}
46+
47+
const onInput = (value) => showToast(`${value}`)
48+
const onDelete = () => showToast('删除')
49+
```
50+
51+
## 身份证键盘
52+
53+
通过 `extra-key` 属性可以设置左下角按键内容，比如需要输入身份证号时，可以将 `extra-key` 设置为 `X`。
54+
55+
```html
56+
<wd-cell title="身份证键盘" is-link @click="showKeyBoard" />
57+
58+
<wd-keyboard v-model:visible="visible" extra-key="X" close-text="完成" @input="onInput" @delete="onDelete" />
59+
```
60+
61+
```ts
62+
const { show: showToast } = useToast()
63+
const visible = ref<boolean>(false)
64+
65+
function showKeyBoard() {
66+
visible.value = true
67+
}
68+
69+
const onInput = (value) => showToast(`${value}`)
70+
const onDelete = () => showToast('删除')
71+
```
72+
73+
## 车牌号键盘
74+
75+
将 `mode` 属性设置为 `car` 来展示车牌号键盘，常用于输入车牌号的场景。
76+
77+
```html
78+
<wd-cell title="车牌号键盘" is-link @click="showKeyBoard" />
79+
80+
<wd-keyboard v-model:visible="visible" mode="car" @input="onInput" @delete="onDelete"></wd-keyboard>
81+
```
82+
83+
```ts
84+
const { show: showToast } = useToast()
85+
const visible = ref<boolean>(false)
86+
87+
function showKeyBoard() {
88+
visible.value = true
89+
}
90+
91+
const onInput = (value) => showToast(`${value}`)
92+
const onDelete = () => showToast('删除')
93+
```
94+
95+
## 带标题的键盘
96+
97+
通过 `title` 属性可以设置键盘标题。
98+
99+
```html
100+
<wd-cell title="带标题的键盘" is-link @click="showKeyBoard" />
101+
102+
<wd-keyboard v-model:visible="visible" title="输入密码" extra-key="." close-text="完成" @input="onInput" @delete="onDelete" />
103+
```
104+
105+
```ts
106+
const { show: showToast } = useToast()
107+
const visible = ref<boolean>(false)
108+
109+
function showKeyBoard() {
110+
visible.value = true
111+
}
112+
113+
const onInput = (value) => showToast(`${value}`)
114+
const onDelete = () => showToast('删除')
115+
```
116+
117+
## 使用 slot 自定义标题
118+
119+
```html
120+
<wd-cell title="使用 slot 自定义标题" is-link @click="showKeyBoard" />
121+
122+
<wd-keyboard v-model:visible="visible" extra-key="." close-text="完成" @input="onInput" @delete="onDelete">
123+
<template #title>
124+
<text style="color: red">自定义标题</text>
125+
</template>
126+
</wd-keyboard>
127+
```
128+
129+
```ts
130+
const { show: showToast } = useToast()
131+
const visible = ref<boolean>(false)
132+
133+
function showKeyBoard() {
134+
visible.value = true
135+
}
136+
137+
const onInput = (value) => showToast(`${value}`)
138+
const onDelete = () => showToast('删除')
139+
```
140+
141+
## 多个额外按键
142+
143+
当 `mode` 为 `custom` 时，支持以数组的形式配置两个 `extra-key`。
144+
145+
```html
146+
<wd-cell title="多个额外按键" is-link @click="showKeyBoard" />
147+
148+
<wd-keyboard v-model:visible="visible" mode="custom" :extra-key="['00', '.']" close-text="完成" @input="onInput" @delete="onDelete" />
149+
```
150+
151+
```ts
152+
const { show: showToast } = useToast()
153+
const visible = ref<boolean>(false)
154+
155+
function showKeyBoard() {
156+
visible.value = true
157+
}
158+
159+
const onInput = (value) => showToast(`${value}`)
160+
const onDelete = () => showToast('删除')
161+
```
162+
163+
## 随机数字键盘
164+
165+
通过 `random-key-order` 属性可以随机排序数字键盘，常用于安全等级较高的场景。
166+
167+
```html
168+
<wd-cell title="随机数字键盘" is-link @click="showKeyBoard" />
169+
170+
<wd-keyboard v-model:visible="visible" random-key-order @input="onInput" @delete="onDelete" />
171+
```
172+
173+
```ts
174+
const { show: showToast } = useToast()
175+
const visible = ref<boolean>(false)
176+
177+
function showKeyBoard() {
178+
visible.value = true
179+
}
180+
181+
const onInput = (value) => showToast(`${value}`)
182+
const onDelete = () => showToast('删除')
183+
```
184+
185+
## 双向绑定
186+
187+
可以通过 `v-model` 绑定键盘当前输入值，并通过 `maxlength` 属性来限制输入长度。
188+
189+
```html
190+
<wd-cell title="双向绑定" :value="value1" is-link @click="showKeyBoard" />
191+
<wd-keyboard
192+
v-model="value1"
193+
:maxlength="6"
194+
v-model:visible="visible"
195+
title="键盘标题"
196+
extra-key="."
197+
close-text="完成"
198+
@input="onInput"
199+
@delete="onDelete"
200+
></wd-keyboard>
201+
```
202+
203+
```ts
204+
const { show: showToast } = useToast()
205+
const visible = ref<boolean>(false)
206+
const value1 = ref<string>('')
207+
208+
function showKeyBoard() {
209+
visible.value = true
210+
}
211+
212+
const onInput = (value) => showToast(`${value}`)
213+
const onDelete = () => showToast('删除')
214+
```
215+
216+
## 展示蒙层遮罩
217+
218+
`hideOnClickOutside`控制键盘弹窗是否有遮罩，通过`modal`控制遮罩是否为透明。
219+
220+
::: tip 提示
221+
当前`modal`仅控制遮罩是否为透明，`hideOnClickOutside`控制弹窗是否有遮罩，当存在遮罩时，点击遮罩就可以关闭键盘，但是键盘展开时必须点击遮罩关闭当前键盘后才可以再点击别的按钮。也可以关闭`hideOnClickOutside`，手动控制键盘是否展示来实现点击外部时收起键盘，这样更灵活。
222+
:::
223+
224+
```html
225+
<wd-cell title="双向绑定" :value="value1" is-link @click="showKeyBoard" />
226+
<wd-keyboard :modal="true" :hide-on-click-outside="true" v-model:visible="visible" @input="onInput" @delete="onDelete" />
227+
```
228+
229+
```ts
230+
const { show: showToast } = useToast()
231+
const visible = ref<boolean>(false)
232+
const value1 = ref<string>('')
233+
234+
function showKeyBoard() {
235+
visible.value = true
236+
}
237+
238+
const onInput = (value) => showToast(`${value}`)
239+
const onDelete = () => showToast('删除')
240+
```
241+
242+
## Attributes
243+
244+
| 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 |
245+
| ------------------- | ------------------------ | --------------------- | -------------------------- | ---------- | ---------------- |
246+
| v-model:visible | 是否展开 | `boolean` | - | `false` | 0.1.65 |
247+
| v-model | 绑定的值 | `string` | - | - | 0.1.65 |
248+
| title | 标题 | `string` | - | - | 0.1.65 |
249+
| mode | 键盘模式 | `string` | `default`, `car`, `custom` | `default` | $LOWEST_VERSION$ |
250+
| zIndex | 层级 | `number` | - | `100` | 0.1.65 |
251+
| maxlength | 最大长度 | `number` | - | `Infinity` | 0.1.65 |
252+
| showDeleteKey | 是否显示删除键 | `boolean` | - | `true` | 0.1.65 |
253+
| randomKeyOrder | 是否随机键盘按键顺序 | `boolean` | - | `false` | 0.1.65 |
254+
| closeText | 确认按钮文本 | `string` | - | - | 0.1.65 |
255+
| deleteText | 删除按钮文本 | `string` | - | - | 0.1.65 |
256+
| closeButtonLoading | 关闭按钮是否显示加载状态 | `boolean` | - | `false` | 0.1.65 |
257+
| modal | 是否显示蒙层遮罩 | `boolean` | - | `false` | 0.1.65 |
258+
| hideOnClickOutside | 是否在点击外部时收起键盘 | `boolean` | - | `true` | 0.1.65 |
259+
| lockScroll | 是否锁定滚动 | `boolean` | - | `true` | 0.1.65 |
260+
| safeAreaInsetBottom | 是否在底部安全区域内 | `boolean` | - | `true` | 0.1.65 |
261+
| extraKey | 额外按键 | `string` / `string[]` | - | - | 0.1.65 |
262+
263+
## Slot
264+
265+
| name | 说明 | 类型 | 最低版本 |
266+
| ----- | ---- | ---- | -------- |
267+
| title | 标题 | - | 1.2.12 |
268+
269+
## Events
270+
271+
| 事件名称 | 说明 | 参数 | 最低版本 |
272+
| -------- | ------------------------------ | ----------- | -------- |
273+
| input | 点击按键时触发 | key: string | - |
274+
| delete | 点击删除键时触发 | - | - |
275+
| close | 点击关闭按钮或非键盘区域时触发 | - | - |
276+
277+
## 外部样式类
278+
279+
| 类名 | 说明 | 最低版本 |
280+
| ------------ | ------------ | -------- |
281+
| custom-class | 根节点样式类 | 0.1.65 |
282+
| custom-style | 根节点样式 | 0.1.65 |

‎src/pages.json‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{
2-
"pages": [{
2+
"pages": [
3+
{
34
"path": "pages/index/Index",
45
"name": "index",
56
"style": {
@@ -194,7 +195,6 @@
194195
"path": "pages/notify/Index",
195196
"name": "toast",
196197
"style": {
197-
198198
"mp-alipay": {
199199
"allowsBounceVertical": "NO"
200200
},
@@ -762,6 +762,16 @@
762762
"navigationBarTitleText": "CountTo 数字滚动"
763763
}
764764
},
765+
{
766+
"path": "pages/keyboard/Index",
767+
"name": "keyboard",
768+
"style": {
769+
"mp-alipay": {
770+
"allowsBounceVertical": "NO"
771+
},
772+
"navigationBarTitleText": "Keyboard 虚拟键盘"
773+
}
774+
},
765775
{
766776
"path": "pages/numberKeyboard/Index",
767777
"name": "numberKeyboard",

‎src/pages/index/Index.vue‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,10 @@ const list = ref([
290290
id: 'countTo',
291291
name: 'CountTo 数字滚动'
292292
},
293+
{
294+
id: 'keyboard',
295+
name: 'Keyboard 虚拟键盘'
296+
},
293297
{
294298
id: 'numberKeyboard',
295299
name: 'NumberKeyboard 数字键盘'

0 commit comments

Comments
 (0)