IME Kit提供输入法框架和输入法服务两类API。用于实现输入法应用,也可以用于实现自绘编辑框以及实现对输入法应用的控制。
IME Kit在输入法软键盘和自绘编辑框时使用ArkUI提供的部分组件、事件、动效、状态管理等能力,例如Text、Button组件,onClick点击事件。

在自绘编辑框中使用输入法:在输入法框架中,可以通过getController方法获取到InputMethodController实例来绑定输入法并监听输入法应用的各种操作,比如插入、删除、选择、光标移动等。这样就可以在自绘编辑框中使用输入法,并实现更加灵活和自由的编辑操作。
对于TextInput,设置inputFilter且输入的字符不为空字符,会导致设置输入框类型(即type接口)附带的文本过滤效果失效。
输入设备开发指导:当用户需要输入文本时,输入法会根据当前是否插入了物理键盘来决定是否弹出虚拟键盘,开发者可以通过监听设备热插拔判断是否有物理键盘插入。
属性 | 值 | 描述 |
|---|---|---|
max | number date | 属性规定元素的最大值。 |
maxlength | number | 属性规定元素中允许的最大字符数。 |
min | number date | 属性规定元素的最小值。 |
multiple | multiple | 属性规定允许用户输入到元素的多个值。 |
pattern | regexp | pattern 属性规定用于验证元素的值的正则表达式。 |
type | button;checkbox;color;date;datetime;datetime-local;email;file;hidden;image;month;number;password;radio;range;reset;search;submit;tel;text;time;url;week | type 属性规定要显示的元素的类型。 |
在密码模式下,设置showPassword属性时,在onSecurityStateChange回调中,建议增加状态同步。
onWillInsert、onDidInsert、onWillDelete、onDidDelete回调仅支持系统输入法的场景。
onWillChange的回调时序晚于onWillInsert、onWillDelete,早于onDidInsert、onDidDelete。
使用RichEditorStyledStringOptions构建的RichEditor组件不支持上述回调。
一般使用Text组件作为自绘编辑框的文本显示组件,状态变量作为Text组件要显示的内容。
应用对于输入内容有校验机制不合理。例如,作为输入框使用的ArkUI组件,未正确设置输入框类型、正则表达过滤器和最大输入字符数限制等,则可能导致无效输入无法被及时拦截。同样,在H5页面中,HTML的<input>标签若未合理设置type属性或pattern正则模式,也会造成输入验证失效,影响用户体验。
修复或者完善对应事件逻辑,优化用户体验。其中以TextInput为例(其他请参考背景知识),添加事件:
TextInput({ text: 'Hello World', placeholder: 'input your word...', controller: this.controller })
.type(InputType.Password)
.showPassword(this.passwordState)
.onChange((value: string) => {
// 文本内容发生变化时触发该回调
console.info('onChange is triggering: ', value);
})
.onSubmit((enterKey: EnterKeyType, event: SubmitEvent) => {
// 按下输入法回车键时触发该回调
console.info('onSubmit is triggering: ', enterKey, event.text);
})
.onTextSelectionChange((selectionStart: number, selectionEnd: number) => {
// 文本选择的位置发生变化或编辑状态下光标位置发生变化时,触发该回调
console.info('onTextSelectionChange is triggering: ', selectionStart, selectionEnd);
})
.onSecurityStateChange((isShowPassword: boolean) => {
// 密码显隐状态切换时,触发该回调
console.info('onSecurityStateChange is triggering: ', isShowPassword);
this.passwordState = isShowPassword;
})
.onWillInsert((info: InsertValue) => {
// 在将要输入时,触发该回调
console.info('onWillInsert is triggering: ', info.insertValue, info.insertOffset);
return true;
})
.onDidInsert((info: InsertValue) => {
// 在输入完成时,触发该回调
console.info('onDidInsert is triggering: ', info.insertValue, info.insertOffset);
})
.onWillDelete((info: DeleteValue) => {
// 在将要删除时,触发该回调
console.info('onWillDelete is triggering: ', info.deleteValue, info.deleteOffset);
return true;
})
.onDidDelete((info: DeleteValue) => {
// 在删除完成时,触发该回调
console.info('onDidDelete is triggering: ', info.deleteValue, info.deleteOffset);
})
.onFocus(() => {
// 绑定通用事件,输入框获焦时触发该回调
console.info('onFocus is triggering');
}) 根据具体场景使用正确的组件能力和状态变量管理。以Text组件作为自绘编辑框的文本显示组件,状态变量inputText作为Text组件要显示的内容为例:
import { inputMethod } from '@kit.IMEKit';
@Component
export struct CustomInput {
@State inputText: string = ''; // inputText作为Text组件要显示的内容。
private isAttach: boolean = false;
private inputController: inputMethod.InputMethodController = inputMethod.getController();
build() {
Text(this.inputText) // Text组件作为自绘编辑框的文本显示组件。
.fontSize(16)
.width('100%')
.lineHeight(40)
.id('customInput')
.onBlur(() => {
this.off();
})
.height(45)
.border({ color: '#554455', radius: 30, width: 1 })
.maxLines(1)
.onClick(() => {
this.attachAndListener(); // 点击控件
})
}
async attachAndListener() { // 绑定和设置监听
focusControl.requestFocus('CustomInput');
try {
await this.inputController.attach(true, {
inputAttribute: {
textInputType: inputMethod.TextInputType.TEXT,
enterKeyType: inputMethod.EnterKeyType.SEARCH
}
});
} catch (error) {
// TODO: Implement error handling.
}
if (!this.isAttach) {
try {
this.inputController.on('insertText', (text) => {
this.inputText += text;
});
} catch (error) {
// TODO: Implement error handling.
}
try {
this.inputController.on('deleteLeft', (length) => {
this.inputText = this.inputText.substring(0, this.inputText.length - length);
});
} catch (error) {
// TODO: Implement error handling.
}
this.isAttach = true;
}
}
off() {
this.isAttach = false;
this.inputController.off('insertText');
this.inputController.off('deleteLeft');
}
}
设置正确的校验机制,并增加提醒,引导用户合法输入。
完整示例:
import { inputMethod } from '@kit.IMEKit';
@Component
export struct CustomInput {
@State inputText: string = ''; // inputText作为Text组件要显示的内容。
private isAttach: boolean = false;
private inputController: inputMethod.InputMethodController = inputMethod.getController();
build() {
Text(this.inputText) // Text组件作为自绘编辑框的文本显示组件。
.fontSize(16)
.width('100%')
.lineHeight(40)
.id('customInput')
.onBlur(() => {
this.off();
})
.height(45)
.border({ color: '#554455', radius: 30, width: 1 })
.maxLines(1)
.onClick(() => {
this.attachAndListener(); // 点击控件
})
}
async attachAndListener() { // 绑定和设置监听
focusControl.requestFocus('CustomInput');
try {
await this.inputController.attach(true, {
inputAttribute: {
textInputType: inputMethod.TextInputType.TEXT,
enterKeyType: inputMethod.EnterKeyType.SEARCH
}
});
} catch (error) {
// TODO: Implement error handling.
}
if (!this.isAttach) {
try {
this.inputController.on('insertText', (text) => {
this.inputText += text;
});
} catch (error) {
// TODO: Implement error handling.
}
try {
this.inputController.on('deleteLeft', (length) => {
this.inputText = this.inputText.substring(0, this.inputText.length - length);
});
} catch (error) {
// TODO: Implement error handling.
}
this.isAttach = true;
}
}
off() {
this.isAttach = false;
this.inputController.off('insertText');
this.inputController.off('deleteLeft');
}
}
@Entry
@Component
struct NavTitleSolution1 {
controller: TextInputController = new TextInputController();
@State passwordState: boolean = false;
build() {
Column() {
TextInput({ text: 'Hello World', placeholder: 'input your word...', controller: this.controller })
.type(InputType.Password)
.showPassword(this.passwordState)
.onChange((value: string) => {
// 文本内容发生变化时触发该回调
console.info('onChange is triggering: ', value);
})
.onSubmit((enterKey: EnterKeyType, event: SubmitEvent) => {
// 按下输入法回车键时触发该回调
console.info('onSubmit is triggering: ', enterKey, event.text);
})
.onTextSelectionChange((selectionStart: number, selectionEnd: number) => {
// 文本选择的位置发生变化或编辑状态下光标位置发生变化时,触发该回调
console.info('onTextSelectionChange is triggering: ', selectionStart, selectionEnd);
})
.onSecurityStateChange((isShowPassword: boolean) => {
// 密码显隐状态切换时,触发该回调
console.info('onSecurityStateChange is triggering: ', isShowPassword);
this.passwordState = isShowPassword;
})
.onWillInsert((info: InsertValue) => {
// 在将要输入时,触发该回调
console.info('onWillInsert is triggering: ', info.insertValue, info.insertOffset);
return true;
})
.onDidInsert((info: InsertValue) => {
// 在输入完成时,触发该回调
console.info('onDidInsert is triggering: ', info.insertValue, info.insertOffset);
})
.onWillDelete((info: DeleteValue) => {
// 在将要删除时,触发该回调
console.info('onWillDelete is triggering: ', info.deleteValue, info.deleteOffset);
return true;
})
.onDidDelete((info: DeleteValue) => {
// 在删除完成时,触发该回调
console.info('onDidDelete is triggering: ', info.deleteValue, info.deleteOffset);
})
.onFocus(() => {
// 绑定通用事件,输入框获焦时触发该回调
console.info('onFocus is triggering');
})
}
.justifyContent(FlexAlign.Center)
.width('100%')
.height('100%');
}
}