uView Next
4.1.6

外观

Keyboard 键盘

约 1679 字大约 6 分钟

2025-10-31

此为uView自定义的键盘面板，内含了数字键盘，车牌号键，身份证号键盘3种模式，都有可以打乱按键顺序的选项。

基本使用

通过mode参数定义键盘的类型，show绑定一个值为布尔值的变量控制键盘的弹出与收起：

  • mode = car (默认值)为汽车键盘，此时顶部工具条中间的提示文字为"车牌号键盘"
  • mode = number为数字键盘，此时顶部工具条中间的提示文字为"数字键盘"
  • mode = idcard 为身份证键盘，此时顶部工具条中间的提示文字为"身份证键盘"
<template>
	<un-page>
		<card :padding="false">
			<un-cell-group>
				<un-cell @click="openNumberKeyboard()" title="数字键盘" :value="input" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/number.png" mode="widthFix"></un-image>
					</template>
				</un-cell>
			</un-cell-group>
		</card>
		<un-keyboard
			v-model="inputStr"
			:mode="keyData.mode"
			:overlay="keyData.overlay"
			:showToolbar="keyData.showToolbar"
			:title="keyData.title"
			:show="show"
			@close="close" 
			@cancel="cancel" 
			@confirm="confirm" 
			@change="change" 
			@backspace="backspace"
		></un-keyboard>
	</un-page>
</template>

<script setup lang="uts">
	import { ref, reactive } from 'vue';
	
	type KeyboardItem = {
		mode: string;
		showToolbar: boolean;
		overlay: boolean;
		title: string;
	}

	// 响应式数据
	const inputStr = ref('');
	const input = ref('');
	const show = ref(false);
	const keyData = reactive<KeyboardItem>({
		mode: '',
		showToolbar: true,
		overlay: true,
		title: '',
	});

	// 重置键盘配置
	function reset() {
		input.value = '';
		inputStr.value = '';
		keyData.mode = '';
		keyData.showToolbar = true;
		keyData.title = '';
	}
	
	// 打开数字键盘
	function openNumberKeyboard() {
		reset();
		keyData.title = '数字键盘';
		keyData.mode = 'number';
		show.value = !show.value;
	}
	
	// 点击键盘按键
	function change(e: string) {
		input.value += e;
	}
	
	// 关闭键盘
	function close() {
		show.value = false;
	}
	
	// 取消
	function cancel() {
		show.value = false;
	}
	
	// 确认
	function confirm() {
		show.value = false;
	}
	
	// 退格
	function backspace() {
		input.value = input.value.slice(0, -1);
	}
</script>

带右侧栏的键盘

通过mode参数设置为custom，并配置extraKey参数可以自定义键盘右侧的按键。

<template>
	<un-page>
		<card :padding="false">
			<un-cell-group>
				<un-cell @click="openCustomKeyboard()" title="带右侧栏的键盘" :value="inputStr" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/number.png" mode="widthFix"></un-image>
					</template>
				</un-cell>
			</un-cell-group>
		</card>
		<un-keyboard
			v-model="inputStr"
			:mode="keyData.mode"
			:showToolbar="keyData.showToolbar"
			:show="show"
			@close="close" 
			@cancel="cancel" 
			@confirm="confirm" 
			@change="change" 
			@backspace="backspace"
		></un-keyboard>
	</un-page>
</template>

<script setup lang="uts">
	// ...其他代码与基本使用示例相同...
	
	// 打开带右侧栏的键盘
	function openCustomKeyboard() {
		reset();
		keyData.mode = 'custom';
		keyData.extraKey = [];
		show.value = !show.value;
	}
</script>

配置额外按键

通过extraKey参数可以配置键盘右侧的额外按键，支持配置多个按键。

<template>
	<un-page>
		<card :padding="false">
			<un-cell-group>
				<un-cell @click="openExtraKeyKeyboard()" title="配置1个按钮" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/number.png" mode="widthFix"></un-image>
					</template>
				</un-cell>
				<un-cell @click="openExtraKeyKeyboard2()" title="配置2个按钮" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/number.png" mode="widthFix"></un-image>
					</template>
				</un-cell>
			</un-cell-group>
		</card>
		<un-keyboard
			v-model="inputStr"
			:mode="keyData.mode"
			:overlay="keyData.overlay"
			:showToolbar="keyData.showToolbar"
			:extraKey="keyData.extraKey" 
			:show="show"
			@close="close" 
			@cancel="cancel" 
			@confirm="confirm" 
			@change="change" 
			@backspace="backspace"
		></un-keyboard>
	</un-page>
</template>

<script setup lang="uts">
	// ...其他代码与基本使用示例相同...
	
	// 打开配置1个按钮的键盘
	function openExtraKeyKeyboard() {
		reset();
		keyData.mode = 'custom';
		keyData.overlay = false;
		keyData.showToolbar = false;
		keyData.extraKey = ['.'];
		show.value = !show.value;
	}

	// 打开配置2个按钮的键盘
	function openExtraKeyKeyboard2() {
		reset();
		keyData.mode = 'custom';
		keyData.overlay = false;
		keyData.showToolbar = false;
		keyData.extraKey = ['00','.'];
		show.value = !show.value;
	}
</script>

身份证键盘

通过mode参数设置为idcard可以使用身份证键盘。

<template>
	<un-page>
		<card :padding="false">
			<un-cell-group>
				<un-cell @click="openCardKeyboard()" title="身份证键盘" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/IdCard.png"
							mode="widthFix"></un-image>
					</template>
				</un-cell>
			</un-cell-group>
		</card>
		<un-keyboard
			v-model="inputStr"
			:mode="keyData.mode"
			:title="keyData.title"
			:random="keyData.random" 
			:show="show"
			@close="close" 
			@cancel="cancel" 
			@confirm="confirm" 
			@change="change" 
			@backspace="backspace"
		></un-keyboard>
	</un-page>
</template>

<script setup lang="uts">
	// ...其他代码与基本使用示例相同...
	
	// 打开身份证键盘
	function openCardKeyboard() {
		reset();
		keyData.title = '身份证键盘';
		keyData.mode = 'idcard';
		keyData.random = false;
		show.value = !show.value;
	}
</script>

车牌号键盘

通过mode参数设置为car可以使用车牌号键盘。

<template>
	<un-page>
		<card :padding="false">
			<un-cell-group>
				<un-cell @click="openCarKeyboard()" title="车牌号键盘" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/car.png"
							mode="widthFix"></un-image>
					</template>
				</un-cell>
				<un-cell @click="openCarSwitch()" title="车牌号键盘（自动切换字母）" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/car.png"
							mode="widthFix"></un-image>
					</template>
				</un-cell>
			</un-cell-group>
		</card>
		<un-keyboard
			v-model="inputStr"
			:mode="keyData.mode"
			:autoChange="keyData.autoChange"
			:show="show"
			@close="close" 
			@cancel="cancel" 
			@confirm="confirm" 
			@change="change" 
			@backspace="backspace"
		></un-keyboard>
	</un-page>
</template>

<script setup lang="uts">
	// ...其他代码与基本使用示例相同...
	
	// 打开车牌号键盘
	function openCarKeyboard() {
		reset();
		keyData.mode = 'car';
		show.value = !show.value;
	}
	
	// 打开车牌号键盘（自动切换字母）
	function openCarSwitch() {
		reset();
		keyData.mode = 'car';
		keyData.autoChange = true;
		show.value = !show.value;
	}
</script>

随机打乱键盘

如果配置random参数为true的话，每次打开键盘，按键的顺序都是随机的，该功能默认是关闭的。

<template>
	<un-page>
		<card :padding="false">
			<un-cell-group>
				<un-cell @click="openRandomNumber()" title="随机打乱数字键盘" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/order.png"
							mode="widthFix"></un-image>
					</template>
				</un-cell>
				<un-cell @click="openRandomIdCard()" title="随机打乱身份证键盘" isLink>
					<template #icon>
						<un-image width="20px" height="20px" src="https://cdn.uviewui.com/uview/demo/keyboard/order.png"
							mode="widthFix"></un-image>
					</template>
				</un-cell>
			</un-cell-group>
		</card>
		<un-keyboard
			v-model="inputStr"
			:mode="keyData.mode"
			:random="keyData.random" 
			:show="show"
			@close="close" 
			@cancel="cancel" 
			@confirm="confirm" 
			@change="change" 
			@backspace="backspace"
		></un-keyboard>
	</un-page>
</template>

<script setup lang="uts">
	// ...其他代码与基本使用示例相同...
	
	// 打开随机键盘
	function openRandomNumber() {
		reset();
		keyData.mode = 'number';
		keyData.random = true;
		show.value = !show.value;
	}
	
	// 打开随机打乱身份证键盘
	function openRandomIdCard() {
		reset();
		keyData.mode = 'idcard';
		keyData.random = true;
		show.value = !show.value;
	}
</script>

API

Props

参数说明类型默认值
mode键盘的类型，number-数字键盘，idcard-身份证键盘，car-车牌号键盘，custom-自定义键盘
Enum
number
modelValue绑定值String''
extraKey自定义键盘右侧的额外按键Array[]
round键盘的圆角大小String | Number5
showToolbar是否显示顶部工具条Booleantrue
title工具条中间的提示文字，如不需要，请传""空字符String-
random是否打乱键盘按键的顺序Booleanfalse
maxlength最大输入长度Number-1
safeAreaInsetBottom是否开启底部安全区适配，开启的话，会在iPhoneX机型底部添加一定的内边距Booleantrue
closeOnClickOverlay是否允许通过点击遮罩关闭键盘Booleantrue
show控制键盘的弹出与收起Booleanfalse
overlay是否显示遮罩，某些时候数字键盘时，用户希望看到自己的数值，所以可能不想要遮罩Booleantrue
zIndex弹出键盘的z-index值String | Number10075
cancelText取消按钮的文字String'取消'
confirmText确认按钮的文字String'确认'
carLang车牌号键盘的语言，zh-中文，en-英文
Enum
zh
autoChange输入一个中文后，是否自动切换到英文Booleanfalse

Events

事件名说明类型
change按键被点击(不包含退格键被点击)
Function
cancel键盘顶部工具条左边的"取消"按钮被点击
Function
confirm键盘顶部工具条右边的"完成"按钮被点击
Function
backspace键盘退格键被点击
Function
close键盘关闭
Function

Copyright © 2026 uView Next