Keyboard Component ^0.7.0

A virtual keyboard component that supports multiple modes, including numeric keyboard, license plate keyboard, and ID card keyboard, with a customizable header and keys.

📌 Platform Differences

APP(vue)	H5	WeChat Mini Program	Alipay Mini Program
✔	✔	✔	✔

2. v-model Binding

The component uses v-model:show to control visibility, and v-model to bind the input value:

<hy-keyboard
    v-model:show="showKeyboard"   <!-- Control show/hide -->
    v-model="inputValue"          <!-- Bind the input value -->
    v-model:car-lang="carLang"    <!-- Effective when mode is car; switches between Chinese and English -->
></hy-keyboard>

3. License Plate Keyboard Mode

The license plate keyboard supports two modes:

Mode	Property	Description	Use Case
Uncontrolled mode	Pass auto-switch-lang	The component manages language switching internally	Simple scenarios, ready to use out of the box
Controlled mode	Pass v-model:car-lang	Manually control language switching	Need to listen to or control the language in the parent component

Uncontrolled mode example:

<!-- Set auto-switch-lang to switch automatically -->
<hy-keyboard mode="car" v-model="value" auto-switch-lang></hy-keyboard>

Controlled mode example:

<hy-keyboard mode="car" v-model="value" v-model:car-lang="carLang"></hy-keyboard>

const carLang = ref<'zh' | 'en'>('zh');

// Manually control the switching logic
const handleInput = (val: string) => {
    if (val.length === 1) {
        carLang.value = 'en';
    }
};

const handleDelete = () => {
    if (carControlledValue.value.length === 1) {
        carLang.value = 'zh';
    }
};

4. custom Mode Description

The keyboard in custom mode has a fixed sidebar on the right side, containing a delete key and a close key:

• The delete key and close key in the sidebar are always displayed and require no extra configuration
• If you need to customize additional key positions, you can use the extra-key property

<!-- custom mode: custom keys at the bottom, fixed delete and close keys on the right -->
<hy-keyboard mode="custom" v-model="value" :extra-key="['00', '.']" close-text="Done"></hy-keyboard>

5. extraKey Property

extraKey supports two formats:

<!-- String: a single extra key, displayed to the left of 0 -->
<hy-keyboard mode="custom" extra-key="+"></hy-keyboard>

<!-- Array: multiple extra keys (effective in custom mode) -->
<hy-keyboard mode="custom" :extra-key="['.', '00']"></hy-keyboard>

6. showDotKey Property

Controls whether to display the decimal point key, which is displayed by default:

<!-- Hide the decimal point -->
<hy-keyboard :show-dot-key="false"></hy-keyboard>

<!-- Show the decimal point (default) -->
<hy-keyboard :show-dot-key="true"></hy-keyboard>

7. randomKeyOrder Property

When set to true, the numeric keys will be shuffled in random order:

<hy-keyboard :random-key-order="true"></hy-keyboard>

Note

The random order is generated only once each time the keyboard is shown; pressing keys while the keyboard is open will not change the positions of other keys.

8. close Event Handling

Clicking the close button or the overlay triggers the close event, but it will not automatically close the keyboard; you need to handle it manually:

<hy-keyboard v-model:show="showKeyboard" @close="showKeyboard = false"></hy-keyboard>

9. ID Card Keyboard

The ID card keyboard automatically includes the X key; it is recommended to use it together with maxlength:

<hy-keyboard mode="idcard" :maxlength="18"></hy-keyboard>

🏯 Basic Usage Examples

Default Numeric Keyboard

<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    close-text="Done"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

const showKeyboard = ref(false);
const value = ref('');

const handleInput = (val: string) => {
    console.log('Input:', val);
};

const handleDelete = () => {
    console.log('Delete');
};

const handleClose = () => {
    console.log('Close');
    showKeyboard.value = false;
};

Keyboard with Right Sidebar

<hy-keyboard
    v-model:show="showKeyboard"
    v-model="value"
    mode="custom"
    close-text="Done"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

ID Card Keyboard

<hy-keyboard
    v-model:show="showKeyboard"
    mode="idcard"
    v-model="value"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

License Plate Keyboard (Uncontrolled Mode)

<hy-keyboard
    v-model:show="showKeyboard"
    mode="car"
    auto-switch-lang="true"
    v-model="value"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

License Plate Keyboard (Controlled Mode)

<hy-keyboard
    v-model:show="showKeyboard"
    mode="car"
    v-model="value"
    v-model:car-lang="carLang"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

const carLang = ref<'zh' | 'en'>('zh');

const handleInput = (val: string) => {
    if (val.length === 1) {
        carLang.value = 'en';
    }
    console.log('License plate input:', val);
};

const handleDelete = () => {
    if (carControlledValue.value.length === 1) {
        carLang.value = 'zh';
    }
    console.log('License plate delete:', carControlledValue.value);
};

⚙️ Keyboard Configuration

Hide the Decimal Point

<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    :show-dot-key="false"
    close-text="Done"
></hy-keyboard>

Custom Extra Keys

<!-- Single extra key -->
<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    extra-key="+"
    close-text="Done"
></hy-keyboard>

<!-- Multiple extra keys (custom mode) -->
<hy-keyboard
    v-model:show="showKeyboard"
    mode="custom"
    v-model="value"
    :extra-key="['00', '.']"
    close-text="Done"
></hy-keyboard>

Random Numeric Keyboard

<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    :random-key-order="true"
    close-text="Done"
></hy-keyboard>

🏷️ Custom Header

Keyboard with Title

<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    title="Title"
    close-text="Done"
></hy-keyboard>

Slot Custom Title

<hy-keyboard v-model:show="showKeyboard" mode="default" v-model="value" close-text="Done">
    <template #title>
        <view class="custom-title">
            <text class="custom-title-text">Custom Title</text>
        </view>
    </template>
</hy-keyboard>

.custom-title {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100%;

    &-text {
        font-size: 32rpx;
        font-weight: 500;
        color: #333;
    }
}

API

Keyboard Props

Parameter	Description	Type	Default
show	Whether to show the keyboard	boolean	false
modelValue	The bound value	string	-
title	Title	string	-
mode	Keyboard mode, optional values: default (numeric keyboard), custom (custom keyboard), car (license plate keyboard), idcard (ID card keyboard)	string	default
zIndex	Z-index level	number	100
maxlength	Maximum input length	number	Infinity
showDeleteKey	Whether to show the delete key	boolean	true
showDotKey	Whether to show the decimal point key	boolean	true
randomKeyOrder	Whether to randomize the keyboard key order	boolean	false
closeText	Confirm button text	string	-
deleteText	Delete button text	string	-
closeButtonLoading	Whether the close button shows a loading state	boolean	false
overlay	Whether to show the overlay	boolean	false
overlayOpacity	Overlay opacity	boolean	false
hideOnClickOutside	Whether to collapse the keyboard when clicking outside	number	0
lockScroll	Whether to lock scrolling	boolean	true
safeAreaInsetBottom	Whether to be within the bottom safe area	boolean	true
extraKey	Extra keys, supports a string or an array of strings	string | string[]	-
carLang	License plate keyboard language mode, optional values: zh (provinces), en (letters); if not passed, it runs in uncontrolled mode	string	-
autoSwitchLang	Whether the license plate keyboard switches language automatically	boolean	false
customStyle	Define external styles to be used	CSSProperties	-
customClass	Custom external class name	string	-

Keyboard Events

Event Name	Description	Callback Parameters
input	Triggered when content is input	text: the input character
delete	Triggered when content is deleted	-
close	Triggered when the keyboard is closed	-
update:show	Triggered when visibility changes	show: current visibility state
update:modelValue	Triggered when the value changes	value: current value
update:carLang	Triggered when the license plate language changes	lang: current language ('zh' or 'en')

Keyboard Slots

Slot Name	Description	Received Values
title	Custom title content	-

CSS Variables

Variable	Description	Default
--hy-keyboard-header-height	Header height	80rpx
--hy-keyboard-header-padding	Header padding	0 32rpx
--hy-keyboard-title-font-size	Title font size	32rpx
--hy-keyboard-close-font-size	Close button font size	28rpx
--hy-keyboard-key-gap	Key gap	Follows --hy-border-margin-padding-sm (10rpx)
--hy-keyboard-sidebar-width	Sidebar width	160rpx
--hy-keyboard-key-height	Key height	100rpx
--hy-keyboard-key-radius	Key border radius	12rpx
--hy-keyboard-key-shadow	Key shadow	0 2rpx 8rpx rgba(0, 0, 0, 0.06)
--hy-keyboard-car-key-height	License plate key height	88rpx
--hy-keyboard-car-key-font-size	License plate key font size	28rpx
--hy-keyboard-key-font-size	Key font size	Follows --hy-font-size-lg (36rpx)
--hy-keyboard-border	Header divider line	Follows --hy-border-line

12:33