diff --git a/zh-cn/application-dev/ui/arkts-common-components-text-input.md b/zh-cn/application-dev/ui/arkts-common-components-text-input.md index 2b9a2819c5c2b71f48333068e5a639fcffc75d99..0533f434d24cbd29e823db2839836072b68f2e9b 100644 --- a/zh-cn/application-dev/ui/arkts-common-components-text-input.md +++ b/zh-cn/application-dev/ui/arkts-common-components-text-input.md @@ -358,6 +358,180 @@ struct Index { ![textinputkeyboardavoid](figures/caretavoid.gif) +## 监听输入状态 + +输入框可以在文本输入的不同时刻触发回调，满足开发者监听文本变化的诉求。相关接口包括[onWillInsert](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md#onwillinsert12)、[onWillDelete](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md#onwilldelete12)、[onDidInsert](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md#ondidinsert12)、[onDidDelete](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md#ondiddelete12)、[onWillChange](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md#onwillchange15)、[onChange](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md#onchange)。可通过设置[enablePreviewText](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md#enablepreviewtext12)属性选择是否开启预上屏。 + +按照是否开启预上屏，分开讨论。用“你好朋友”和"hello my dear friend"举例，列举键盘输入、键盘删除、文本选择菜单粘贴、文本选择菜单剪切、剪贴板粘贴共5种场景下，输入框能触发的回调。 + +### 关闭预上屏 + +设置enablePreviewText(false)，或者在输入法中关闭预上屏功能，可以关闭预上屏。 + +1.键盘输入 + +- 输入中文拼音：如输入拼音"nihao"，在输入"n-i-h-a-o"时，输入的每个音素，都不触发任何回调。
+- 输入中文候选词：拼音"nihao"输入完成之后，点击候选词“你好”，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+- 点击中文联想词：汉字“你好”输入完成后，点击联想词“朋友”，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+- 输入英文：如输入"hello"，在输入"h-e-l-l-o"时，输入的每个字母，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+ +2.文本选择菜单粘贴 + +- 通过文本选择菜单粘贴中文：复制"你好朋友"，双击空白文本框，点击文本选择菜单中的粘贴按钮，依次触发onWillChange、onChange回调。
+ +3.剪贴板粘贴 + +- 通过剪贴板粘贴中文：复制"你好朋友"，点击键盘最上方的剪贴板，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+ +4.键盘删除 + +- 通过键盘删除中文：文本框中有“你好朋友”时，光标移动到“友”字后面，点击软键盘的删除键，依次触发onWillDelete、onWillChange、onDidDelete、onChange回调。
+ +5.文本选择菜单剪切 + +- 通过文本选择菜单剪切中文：文本框中有“你好朋友”时，选择“友”字，点击文本选择菜单中的剪切按钮，依次触发onWillChange、onChange回调。
+ +> **说明：** +> +> 关闭预上屏时，文本选择菜单粘贴英文、剪贴板粘贴英文、键盘删除英文、文本选择菜单剪切英文场景下触发的回调，和增删中文的场景下触发的回调相同。 + +### 开启预上屏 + +设置enablePreviewText(true)，并且在输入法中开启预上屏功能，可以开启预上屏。 + +1.键盘输入 + +- 输入中文拼音：如输入拼音"nihao"，在输入"n-i-h-a-o"时，输入的每个音素，依次触发onWillChange、onChange回调。
+- 输入中文候选词：拼音"nihao"输入完成后，点击候选词“你好”，依次触发onWillChange、onChange回调。
+- 点击中文联想词：汉字“你好”输入完成后，点击联想词“朋友”，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+- 输入英文字母：如输入单词"hello"，在输入"h-e-l-l-o"时，输入的每个字母，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+- 点击英文候选词：在字母"h-e-l-l-o"输入完成后，点击候选词"hello"，触发两次onWillChange回调。
+- 点击英文联想词：单词"hello"输入完成后，点击联想词"my"，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+ +2.文本选择菜单粘贴 + +- 粘贴中文：复制“你好朋友”，双击空白文本框，点击文本选择菜单中的粘贴按钮，依次触发onWillChange、onChange回调。
+ +3.剪贴板粘贴 + +- 通过剪贴板粘贴中文：复制“你好朋友”，点击键盘最上方的剪贴板，依次触发onWillInsert、onWillChange、onDidInsert、onChange回调。
+ +4.键盘删除 + +- 通过键盘删除中文拼音：如输入拼音"nihao"，在输入"n-i-h-a-o"之后，点击软键盘的删除键，依次触发onWillChange、onChange回调。
+- 通过键盘删除中文汉字：文本框中有“你好朋友”时，光标移动到“友”字后面，点击软键盘的删除键，依次触发onWillDelete、onWillChange、onDidDelete、onChange回调。
+- 通过键盘删除英文：文本框中有"hello"时，光标移动到字母"o"，点击软键盘的删除键，依次触发onWillDelete、onWillChange、onDidDelete、onChange回调。
+ +5.文本选择菜单剪切 + +- 剪切中文：文本框中有“你好朋友”时，选择“友”字，点击文本选择菜单中的剪切按钮，依次触发onWillChange、onChange回调。
+ +> **说明：** +> +> 开启预上屏时，文本选择菜单粘贴英文、剪贴板粘贴英文、文本选择菜单剪切英文场景下触发的回调，和增删中文的场景下触发的回调相同。 + +### 示例 （增删文本触发回调） + +该示例开启、关闭预上屏时，增删中英文触发的回调。 + +``` +@Entry +@Component +struct demo { + @State orderOnWillChange: number = 0; + @State orderOnWillInsert: number = 0; + @State orderOnWillDelete: number = 0; + @State orderOnDidInsert: number = 0; + @State orderOnDidDelete: number = 0; + @State orderOnChange: number = 0; + @State sharedOrder: number = 0; + @State valueEnablePreviewText: boolean = false; + + build() { + Column({ space: 20 }) { + Text() { + Span('用于复制的文本：\n') + Span('你好朋友\n') + Span('hello my dear friend') + } + .copyOption(CopyOptions.LocalDevice) + + TextInput() // 增删文本触发回调 + .margin(20) + .borderWidth(1) + .onWillChange(() => { + this.sharedOrder++; + this.orderOnWillChange = this.sharedOrder; + return true; + }) + .onWillInsert(() => { + this.sharedOrder++; + this.orderOnWillInsert = this.sharedOrder; + return true; + }) + .onWillDelete(() => { + this.sharedOrder++; + this.orderOnWillDelete = this.sharedOrder; + return true; + }) + .onDidInsert(() => { + this.sharedOrder++; + this.orderOnDidInsert = this.sharedOrder; + }) + .onDidDelete(() => { + this.sharedOrder++; + this.orderOnDidDelete = this.sharedOrder; + }) + .onChange(() => { + this.sharedOrder++; + this.orderOnChange = this.sharedOrder; + }) + .enablePreviewText(this.valueEnablePreviewText) + + Flex({ wrap: FlexWrap.Wrap }) { + Text('callback').width('50%') + Text('order').width('50%') // 回调触发顺序 + Text('onWillChange').width('50%') + Text(`${this.orderOnWillChange}`).width('50%') + Text('onWillInsert').width('50%') + Text(`${this.orderOnWillInsert}`).width('50%') + Text('onWillDelete').width('50%') + Text(`${this.orderOnWillDelete}`).width('50%') + Text('onDidInsert').width('50%') + Text(`${this.orderOnDidInsert}`).width('50%') + Text('onDidDelete').width('50%') + Text(`${this.orderOnDidDelete}`).width('50%') + Text('onChange').width('50%') + Text(`${this.orderOnChange}`).width('50%') + Text('enablePreviewText').width('50%') + Text(`${this.valueEnablePreviewText}`).width('50%') + } + .width('80%') + + Button('reset order') // 重置触发顺序记录 + .onClick(() => { + this.orderOnWillInsert = 0; + this.orderOnWillChange = 0; + this.orderOnDidInsert = 0; + this.orderOnWillDelete = 0; + this.orderOnDidDelete = 0; + this.orderOnChange = 0; + this.sharedOrder = 0; + }) + + Text('测试预上屏场景，需要安装支持预上屏的输入法') + Button('reverse enablePreviewText') // 修改enablePreviewText + .onClick(() => { + this.valueEnablePreviewText = !this.valueEnablePreviewText; + }) + } + .height('100%') + } +} +``` + +![text_input_event_case_1](./figures/text_input_event_case_1.jpeg) + ## 相关实例 针对文本输入开发，有以下相关实例可供参考： diff --git a/zh-cn/application-dev/ui/figures/text_input_event_case_1.jpeg b/zh-cn/application-dev/ui/figures/text_input_event_case_1.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..b8eba6f25cb5bd1cb9fab8d15f11d53adc44338f Binary files /dev/null and b/zh-cn/application-dev/ui/figures/text_input_event_case_1.jpeg differ