本示例介绍如何使用TextInput组件实现自定义车牌号输入键盘场景,主要包括TextInput.customKeyboard绑定自定义键盘、自定义键盘布局和状态更新等知识点。
实现思路
1. 使用TextInput的customKeyboard的属性方法来设置自定义键盘
当设置自定义键盘时,输入框激活后不会打开系统输入法,而是加载应用指定的自定义组件,针对系统键盘的enterKeyType属性设置将无效。自定义键盘采用覆盖原始界面的方式呈现,不会对应用原始界面产生压缩或者上提。默认在输入控件失去焦点时,关闭自定义键盘,开发者也可以通过TextInputController.stopEditing方法控制键盘关闭。
2. 自定义键盘布局
本文主要介绍车牌号输入键盘的布局,还包含其他的如数字键盘、大小写键盘等
键盘枚举类型:
- 键盘类型分为省份键盘、数字+大写字母键盘、数字键盘,大写、小写键盘,特殊字符键盘
- 键盘按键类型分为输入操作INPUT、删除操作DELETE、切换数字键盘操作NUMERIC、切换大小写键盘CAPSLOCK、切换数字键盘SPECIAL、切换省份键盘、切换数字+大写字母键盘共七种类型
/**
* 键盘类型枚举
*/
export enum EKeyboardType {
PROVINCE, // 省份键盘
NUMERIC, // 数字键盘
NUMERIC_UPPERCASE, // 数字大写字母键盘
UPPERCASE, // 大写字母键盘
LOWERCASE, // 小写字母键盘
SPECIAL, // 特殊字符键盘
}
/**
* 键盘按键类型枚举
*/
export enum EKeyType {
INPUT, // 输入类型,输入具体的值
DELETE, // 删除一个输入字符
NUMERIC, // 切换数字键盘
CAPSLOCK, // 切换大小写键盘
SPECIAL, // 切换特殊字符键盘
PROVINCE, // 切换省份键盘
NUMERIC_CAPSLOCK // 切换数字大写字母键盘
}
在真实业务场景下,自定义键盘数据包括值、UI属性、位置等都通过数据请求来下发,键盘按键数据接口定义如下:
/**
* 键盘按键数据接口
*/
export interface IKeyAttribute {
label: string | Resource;
value?: string;
type?: EKeyType;
fontSize?: number;
fontColor?: string | Color;
backgroundColor?: string | Color;
position?: [number, number, number, number];
}
自定义键盘布局:分为标题栏和键盘两部分,键盘使用Grid布局,每个按键GridItem的值、UI属性和位置都通过数据请求下发,不需要额外计算。
数字键盘为4*3的网格布局,但是大小写键盘和特殊字符键盘的布局为不规则布局,如果设置为4 * 10的网格,有的按键占用1 * 1.5,但是GridItem属性不支持占用非整数列。本文将该场景下将网格拆分为更小的单元,为4 * 20网格布局,每个字母按键占1 * 2,删除按键则占1 * 3,空格则占1 * 10,这样就保证每个按键都要占用整数单元。
Column() {
this.titleBar();
Grid() {
// 性能知识点:此处数据项较少,一屏内可以展示所有数据项,使用了ForEach。在数据项多的列表git滚动场景下,推荐使用LazyForEach。
ForEach(this.items, (item: IKeyAttribute) => {
GridItem() {
this.myGridItem(item)
}
.width($r("app.string.vehicle_keyboard_one_hundred_percent"))
.height(this.itemHeight)
.rowStart(item?.position?.[0])
.rowEnd(item?.position?.[1])
.columnStart(item?.position?.[2])
.columnEnd(item?.position?.[3])
.backgroundColor(item.backgroundColor)
.borderRadius($r("app.integer.vehicle_keyboard_keyboard_radius"))
.onClick(() => {
this.onKeyboardEvent?.(item);
if (item.type === EKeyType.CAPSLOCK && typeof item.label === 'object') {
if (this.curKeyboardType === EKeyboardType.LOWERCASE) {
item.label = $r("app.media.vehicle_keyboard_capslock_white");
} else {
item.label = $r("app.media.vehicle_keyboard_capslock_black");
}
}
})
}, (item: IKeyAttribute, index: number) => JSON.stringify(item) + index)
}
.margin({ bottom: $r("app.integer.vehicle_keyboard_keyboard_marin_bottom") })
.columnsTemplate(this.curKeyboardType === EKeyboardType.NUMERIC ? "1fr 1fr 1fr" :
"1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr")
.rowsTemplate("1fr 1fr 1fr 1fr") // Grid高度均分成4份
.rowsGap(this.rowSpace) // 设置行间距
.columnsGap(this.columnSpace) // 设置列间距
.width($r("app.string.vehicle_keyboard_one_hundred_percent"))
.height(this.itemHeight * this.rowCount + this.rowSpace * (this.rowCount - 1))
}
.width($r("app.string.vehicle_keyboard_one_hundred_percent"))
.padding({ left: this.columnSpace, right: this.columnSpace })
.backgroundColor(Color.Black)
3. 状态更新
主要是子组件自定义键盘的按键事件如何传递到父组件,可以在父组件定义好键盘按键事件响应函数onKeyboardEvent,传递给子组件,然后子组件按键时调用父组件传递过来的onKeyboardEvent即可。需要注意的是,在子组件中,必须定义inputValue且使用@Link装饰器,这样能保证子组件调用时onKeyboardEvent时inputValue不为空,父子组件数据双向更新。
/**
* 键盘按键事件响应函数
* @param item 键盘按键数据项
*/
onKeyboardEvent(item: IKeyAttribute) {
switch (item.type) {
// 输入类型,更新输入内容
case EKeyType.INPUT:
this.inputValue += item.value;
break;
// 删除一个已输入的末尾字符
case EKeyType.DELETE:
this.inputValue = this.inputValue.slice(0, -1);
break;
// 切换数字字符键盘
case EKeyType.NUMERIC:
if (this.curKeyboardType !== EKeyboardType.NUMERIC) {
this.curKeyboardType = EKeyboardType.NUMERIC;
this.items = numericKeyData;
}
break;
// 切换大小写
case EKeyType.CAPSLOCK:
if (this.curKeyboardType === EKeyboardType.LOWERCASE) {
// 切换大写字母键盘
this.curKeyboardType = EKeyboardType.UPPERCASE;
this.items = upperCaseKeyData;
} else {
// 切换小写字母键盘
this.curKeyboardType = EKeyboardType.LOWERCASE;
this.items = lowerCaseKeyData;
}
break;
// 切换特殊字符键盘
case EKeyType.SPECIAL:
if (this.curKeyboardType !== EKeyboardType.SPECIAL) {
this.curKeyboardType = EKeyboardType.SPECIAL;
this.items = specialKeyData;
}
break;
case EKeyType.NUMERIC_CAPSLOCK:
if (this.curKeyboardType !== EKeyboardType.SPECIAL) {
this.curKeyboardType = EKeyboardType.NUMERIC_UPPERCASE;
this.items = numberUpperCaseKeyData;
}
break;
case EKeyType.PROVINCE:
if (this.curKeyboardType !== EKeyboardType.SPECIAL) {
this.curKeyboardType = EKeyboardType.PROVINCE;
this.items = provinceKeyData;
}
break;
default:
// logger.info('Sorry, we are out of input type.')
}
}
4. 具体使用
添加TextInput组件,并调用customKeyboard属性方法绑定自定义车牌号键盘
/**
* 自定义键盘组件Builder
*/
@Builder
customKeyboardBuilder() {
VehicleKeyboard({
items: this.items,
inputValue: this.inputValue,
curKeyboardType: this.curKeyboardType,
onKeyboardEvent: this.onKeyboardEvent,
controller: this.controller
})
}
TextInput({
text: this.inputValue,
placeholder: '请输入车牌号',
controller: this.controller
})
.customKeyboard(this.customKeyboardBuilder()) // TODO:知识点: 绑定自定义车牌号键盘
.height($r("app.integer.vehicle_keyboard_text_input_height"))
.margin({ top: $r("app.integer.vehicle_keyboard_common_margin_padding") })
5. 运行截图