shop-wx/doc/wot-design-uni/docs/en-US/component/keyboard.md

version
1.3.10

Keyboard

Virtual keyboard for inputting numbers, passwords, ID cards, or license plate numbers.

Basic Usage

You can control the keyboard's visibility through v-model:visible.

<wd-cell title="Default Keyboard" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" @input="onInput" @delete="onDelete"></wd-keyboard>

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Keyboard with Right Sidebar

Set the mode property to custom to display the keyboard's right sidebar, commonly used for inputting amounts.

<wd-cell title="Keyboard with Right Sidebar" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" mode="custom" extra-key="." close-text="Done" @input="onInput" @delete="onDelete"></wd-keyboard>

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

ID Card Keyboard

You can set the content of the bottom-left button through the extra-key property. For example, when inputting ID card numbers, you can set extra-key to X.

<wd-cell title="ID Card Keyboard" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" extra-key="X" close-text="Done" @input="onInput" @delete="onDelete" />

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

License Plate Keyboard

Set the mode property to car to display the license plate keyboard, commonly used for inputting license plate numbers.

<wd-cell title="License Plate Keyboard" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" mode="car" @input="onInput" @delete="onDelete"></wd-keyboard>

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

License Plate Keyboard Language Control

You can control the language mode of the license plate keyboard through the car-lang property, supporting Chinese provinces (zh) and English letters (en). Use the auto-switch-lang property to control whether to automatically switch languages.

<!-- Controlled mode: Manual language switching -->
<wd-cell title="License Plate Keyboard (Controlled)" :value="value" is-link @click="showKeyBoard" />

<wd-keyboard v-model="value" v-model:visible="visible" v-model:car-lang="lang" mode="car" @input="onInput" @delete="onDelete"></wd-keyboard>

<!-- Uncontrolled mode: Disable auto-switching -->
<wd-cell title="License Plate Keyboard (No Auto-switch)" :value="value2" is-link @click="showKeyBoard2" />

<wd-keyboard v-model="value2" v-model:visible="visible2" mode="car" auto-switch-lang @input="onInput" @delete="onDelete"></wd-keyboard>

const { show: showToast } = useToast()
const visible = ref<boolean>(false)
const visible2 = ref<boolean>(false)
const value = ref<string>('')
const value2 = ref<string>('')
const lang = ref<'zh' | 'en'>('zh')

function showKeyBoard() {
  visible.value = true
}

function showKeyBoard2() {
  visible2.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Keyboard with Title

You can set the keyboard title through the title property.

<wd-cell title="Keyboard with Title" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" title="Enter Password" extra-key="." close-text="Done" @input="onInput" @delete="onDelete" />

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Custom Title Using Slot

<wd-cell title="Custom Title Using Slot" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" extra-key="." close-text="Done" @input="onInput" @delete="onDelete">
  <template #title>
    <text style="color: red">Custom Title</text>
  </template>
</wd-keyboard>

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Multiple Extra Keys

When mode is set to custom, you can configure two extra-key values in array form.

<wd-cell title="Multiple Extra Keys" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" mode="custom" :extra-key="['00', '.']" close-text="Done" @input="onInput" @delete="onDelete" />

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Random Number Keyboard

You can randomly arrange the number keyboard through the random-key-order property, commonly used in high-security scenarios.

<wd-cell title="Random Number Keyboard" is-link @click="showKeyBoard" />

<wd-keyboard v-model:visible="visible" random-key-order @input="onInput" @delete="onDelete" />

const { show: showToast } = useToast()
const visible = ref<boolean>(false)

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Two-way Binding

You can bind the keyboard's current input value through v-model and limit the input length through the maxlength property.

<wd-cell title="Two-way Binding" :value="value1" is-link @click="showKeyBoard" />
<wd-keyboard
  v-model="value1"
  :maxlength="6"
  v-model:visible="visible"
  title="Keyboard Title"
  extra-key="."
  close-text="Done"
  @input="onInput"
  @delete="onDelete"
></wd-keyboard>

const { show: showToast } = useToast()
const visible = ref<boolean>(false)
const value1 = ref<string>('')

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Display Modal Overlay

hideOnClickOutside controls whether the keyboard popup has an overlay, and modal controls whether the overlay is transparent.

::: tip Currently modal only controls whether the overlay is transparent, hideOnClickOutside controls whether the popup has an overlay. When there is an overlay, clicking the overlay can close the keyboard, but when the keyboard is open, you must click the overlay to close the current keyboard before you can click other buttons. You can also disable hideOnClickOutside and manually control whether the keyboard is displayed to implement closing the keyboard when clicking outside, which is more flexible. :::

<wd-cell title="Two-way Binding" :value="value1" is-link @click="showKeyBoard" />
<wd-keyboard :modal="true" :hide-on-click-outside="true" v-model:visible="visible" @input="onInput" @delete="onDelete" />

const { show: showToast } = useToast()
const visible = ref<boolean>(false)
const value1 = ref<string>('')

function showKeyBoard() {
  visible.value = true
}

const onInput = (value) => showToast(`${value}`)
const onDelete = () => showToast('Delete')

Attributes

Parameter	Description	Type	Options	Default	Version
v-model:visible	Whether to display	boolean	-	false	1.3.10
v-model	Bound value	string	-	-	1.3.10
title	Title	string	-	-	1.3.10
mode	Keyboard mode	string	default, car, custom	default	1.3.10
zIndex	Z-index	number	-	100	1.3.10
maxlength	Maximum length	number	-	Infinity	1.3.10
showDeleteKey	Whether to show delete key	boolean	-	true	1.3.10
randomKeyOrder	Whether to randomize keyboard key order	boolean	-	false	1.3.10
closeText	Confirm button text	string	-	-	1.3.10
deleteText	Delete button text	string	-	-	1.3.10
closeButtonLoading	Whether close button shows loading state	boolean	-	false	1.3.10
modal	Whether to show modal overlay	boolean	-	false	1.3.10
hideOnClickOutside	Whether to close keyboard when clicking outside	boolean	-	true	1.3.10
lockScroll	Whether to lock background scroll, when locked, content in the overlay will also not scroll	boolean	-	true	1.3.10
safeAreaInsetBottom	Whether to enable bottom safe area	boolean	-	true	1.3.10
extraKey	Extra key	string / string[]	-	-	1.3.10
root-portal	Whether to detach from the page, used to solve various fixed positioning issues	boolean	-	false	1.11.0
v-model:carLang	License plate keyboard language mode, effective when mode=car	string	zh, en	-	1.13.0
autoSwitchLang	Whether to automatically switch license plate keyboard language, effective when mode=car and car-lang is uncontrolled	boolean	-	false	1.13.0

Slot

name	Description	Type	Version
title	Title	-	1.2.12

Events

Event Name	Description	Parameters	Version
input	Triggered when a key is pressed	key: string	-
delete	Triggered when delete key is pressed	-	-
close	Triggered when close button or outside is clicked	-	-

External Style Classes

Class Name	Description	Version
custom-class	Root node style class	1.3.10
custom-style	Root node style	1.3.10