TextController动态文本选择高亮实战：HarmonyOS NEXT 6.1新特性解析

鸿蒙专家

在鸿蒙应用开发中，文本交互的深度与流畅度直接影响用户体验。以往，普通Text组件的文本选区依赖于用户长按或双击手势，开发者无法通过代码主动控制高亮区域，这限制了AI划词、搜索高亮、语音同步标注等创新功能的实现。HarmonyOS NEXT 6.1（API 23）对ArkUI的TextController进行了里程碑式升级，新增了setTextSelection()接口，使开发者能够通过代码动态指定文本索引区间，触发原生高亮框选，并支持系统菜单联动。本文将结合实战，深入解析该接口的能力、使用方法和常见避坑点。

一、能力与原理
在ArkUI的文本渲染管道中，Text组件开启复制能力（如设置copyOption）后，底层会激活选区高亮渲染层。API 23之前，该层完全由系统手势状态机控制，应用层无法介入。setTextSelection()的出现打破了这一封闭链路：调用时，指令绕过手势层，直接将起始索引（selectionStart）和结束索引（selectionEnd）注入底层状态机，文本测量层（Paragraph）立即计算字符物理坐标，在无需重排的前提下局部叠加蓝色高亮色块，并可根据选项决定是否弹出系统级复制、全选菜单。

二、API定义与约束
TextController上的setTextSelection()方法原型如下：

2. setTextSelection(
3.   selectionStart: number | undefined,
4.   selectionEnd: number | undefined,
5.   options?: SelectionOptions
6. ): void;

复制代码

参数说明：
- selectionStart：起始索引，范围[0, +∞)。负数或undefined强制按0处理。
- selectionEnd：结束索引，范围[0, +∞)。负数或undefined强制按0处理。
- options：可选，SelectionOptions对象，其menuPolicy字段支持SHOW（弹出菜单）、HIDE（隐藏菜单）、DEFAULT（默认行为）。

生效前置条件：
- 必须将Text组件的copyOption设置为非None值（如CopyOptions.InApp或CopyOptions.LocalDevice），否则调用静默失效。
- 不能与跑马灯模式（TextOverflow.MARQUEE）同时使用，否则不生效。

边界规则：
- 当selectionStart ≥ selectionEnd时，视为无效选区，无任何选中效果。
- 索引超出文本总字符数（textSize）时，自动截断为textSize边界。
- 若选中索引对应的字符因截断（如textOverflow）而不可见，则高亮不生效。
- 在PC/2in1设备上，即使设置MenuPolicy.SHOW也不会主动弹出菜单，以符合桌面交互习惯。
- Emoji字符会作为整体被完整选中。

三、实战代码落地
下面是一个完整的Demo示例，展示了如何在ArkUI中使用TextController实现动态选区高亮，并提供索引调整面板和诊断日志。

2. import { router } from '@kit.ArkUI';
4. @Entry
5. @Component
6. struct TextSelectionDetail {
7.   private textController: TextController = new TextController();
8.   @State selectionStartInput: number = 0;
9.   @State selectionEndInput: number = 10;
10.   @State selectionLogs: string = '输入起始和结束索引，点击按钮触发动态选择高亮';
11.   private testTextValue: string = 'HarmonyOS NEXT 极客排版与动态选区高亮技术（API 23）';
13.   build() {
14.     Column() {
15.       // 导航栏
16.       Row() {
17.         Button('返回')
18.           .onClick(() => { router.back(); })
19.           .backgroundColor('#F5A623').fontColor('#000000').height(36).margin({ right: 16 })
20.         Text('TextController 动态选区高亮实战')
21.           .fontColor('#FFFFFF').fontSize(18).fontWeight(FontWeight.Bold)
22.       }
23.       .width('100%').height(56).backgroundColor('#111111').padding({ left: 16, right: 16 })
25.       Column() {
26.         // 文本展示区
27.         Column() {
28.           Text('【动态选区测试 Text 组件】')
29.             .fontSize(14).fontColor('#F5A623').fontWeight(FontWeight.Bold).margin({ bottom: 12 })
30.           Text(this.testTextValue, { controller: this.textController })
31.             .fontSize(16).fontColor('#FFFFFF').lineHeight(24)
32.             .copyOption(CopyOptions.InApp) // 核心：必须设置非None
33.             .width('100%').padding(12).backgroundColor('#111111').borderRadius(8).margin({ bottom: 8 })
34.           Text(`文本总字符数 (textSize)：${this.testTextValue.length}`)
35.             .fontSize(12).fontColor('#888888')
36.         }
37.         .width('100%').padding(16).backgroundColor('#161616').borderRadius(10)
38.         .border({ width: 1, color: '#2C2C2C' }).margin({ bottom: 20 })
40.         // 索引控制面板
41.         Column() {
42.           Text('【选区索引精确控制器】')
43.             .fontSize(14).fontColor('#F5A623').fontWeight(FontWeight.Bold).margin({ bottom: 12 })
44.           Row({ space: 12 }) {
45.             Column() {
46.               Text('起始位置 (Start)').fontSize(12).fontColor('#A0A0A0').margin({ bottom: 6 })
47.               TextInput({ text: this.selectionStartInput.toString() })
48.                 .width('100%').height(40).type(InputType.Number)
49.                 .backgroundColor('#1A1A1A').fontColor('#FFFFFF')
50.                 .onChange((value: string) => { this.selectionStartInput = parseInt(value) || 0; })
51.             }.flexGrow(1)
52.             Column() {
53.               Text('结束位置 (End)').fontSize(12).fontColor('#A0A0A0').margin({ bottom: 6 })
54.               TextInput({ text: this.selectionEndInput.toString() })
55.                 .width('100%').height(40).type(InputType.Number)
56.                 .backgroundColor('#1A1A1A').fontColor('#FFFFFF')
57.                 .onChange((value: string) => { this.selectionEndInput = parseInt(value) || 0; })
58.             }.flexGrow(1)
59.           }
60.           .width('100%').margin({ bottom: 16 })
62.           Row({ space: 10 }) {
63.             Button('触发 setTextSelection')
64.               .onClick(() => {
65.                 try {
66.                   this.textController.setTextSelection(
67.                     this.selectionStartInput,
68.                     this.selectionEndInput,
69.                     { menuPolicy: MenuPolicy.SHOW }
70.                   );
71.                   this.selectionLogs = `执行选区高亮：[${this.selectionStartInput}, ${this.selectionEndInput}] 成功触发`;
72.                 } catch (err) {
73.                   this.selectionLogs = `执行失败：${JSON.stringify(err)}`;
74.                 }
75.               })
76.               .backgroundColor('#E65100').fontColor('#FFFFFF').height(40).flexGrow(1)
77.             Button('清除选区')
78.               .onClick(() => {
79.                 this.textController.setTextSelection(0, 0);
80.                 this.selectionLogs = '选区已被重置清空';
81.               })
82.               .backgroundColor('#2C2C2C').fontColor('#FFFFFF').height(40)
83.           }
84.           .width('100%').margin({ bottom: 12 })
86.           Text(this.selectionLogs)
87.             .fontSize(12).fontColor('#888888').lineHeight(16).width('100%')
88.         }
89.         .width('100%').padding(16).backgroundColor('#161616').borderRadius(10)
90.         .border({ width: 1, color: '#2C2C2C' })
91.       }
92.       .width('100%').flexGrow(1).padding(16).backgroundColor('#000000')
93.     }
94.     .height('100%').width('100%').backgroundColor('#000000')
95.   }
96. }

复制代码

四、运行效果与性能
在实际设备测试中，设置起始索引0、结束索引10并触发后，文本“HarmonyOS ”立即被蓝色高亮覆盖，同时弹出系统原生复制/全选菜单。即使以30Hz频率快速触发，CPU占用率仍维持在个位数，无任何卡顿或重排抖动。索引超出文本长度时，底层自动截断至边界，选区顺滑贴合末尾字符。

五、避坑指南
1. CopyOptions.None导致静默失效：如果忘记设置copyOption或错误设为None，setTextSelection调用后无任何视觉反馈。务必显式设置：

2. .copyOption(CopyOptions.InApp) // 或 CopyOptions.LocalDevice

复制代码

2. 不可见截断区域导致选择哑弹：当Text组件因尺寸限制或textOverflow截断导致部分字符不可见时，选中不可见区域不会触发高亮。如需高亮超出边缘的文本，应关闭截断或使用滚动容器确保所有字符在排版树上可见。

六、总结
setTextSelection()为鸿蒙应用带来了原生级别的动态选区控制能力，彻底解放了长按手势的束缚。通过将高亮渲染下沉至底层文本引擎，实现了零重排的高性能交互，并完美兼容系统级菜单。该接口非常适合AI划词、动态标注、语音朗读同步高亮、全文搜索关键词高亮等场景，建议开发者在API 23及以上版本的项目中积极采用。

热心网友4

感谢分享！这个 `setTextSelection()` 接口确实很实用，以前只能靠用户手势，现在可以代码控制高亮，对做 AI 划词、语音同步标注这类功能太有帮助了。有个小疑问：如果文本组件设置了多种 fontColor 或富文本样式（比如通过 Span），高亮覆盖后原来的颜色会被覆盖吗？还是说蓝色高亮是半透明叠加的？期待后续更多实践分享。