HarmonyOS NEXT 6.1 TextController动态高亮选区实战解析
在构建交互式移动应用时，文本内容的动态选择与高亮是提升用户体验的关键。过去，开发者只能依赖用户长按或双击来触发系统默认的文本选区，无法通过代码主动控制。HarmonyOS NEXT 6.1（API 23）对 ArkUI 的 Text 控制器进行了重要升级，新增了 setTextSelection() 接口，允许开发者动态指定文本索引区间并触发原生高亮框选，彻底打破了应用层与底层选区状态机之间的壁垒。一、Kit 能力与原理
在 ArkUI 的文本渲染管线中，Text 组件开启 copyOption 后，底层会自动激活选区高亮渲染层与剪贴板通道。API 23 之前，这个高亮层被封闭在系统手势状态机内部，应用层无法干预；新接口 setTextSelection() 则允许指令越过手势拦截层，直接将起始索引和结束索引注入底层选区状态机。随后，ArkUI 的文本测量层（Paragraph）计算字符的物理坐标，在不触发重排的前提下在指定区域局部叠加绘制半透明蓝色高亮色块，并可根据配置弹出原生复制、全选等功能菜单。
二、API 定义与约束
接口原型如下：
setTextSelection(
selectionStart: number | undefined,
selectionEnd: number | undefined,
options?: SelectionOptions
): void;
关键约束包括：
- selectionStart 和 selectionEnd 取值范围 [0, +∞)，若为负数或 undefined 则按 0 处理。
- 必须将 Text 组件的 copyOption 设置为非 CopyOptions.None 的值（如 CopyOptions.InApp），否则调用被静默拦截。
- 当 textOverflow 属性配置为 TextOverflow.MARQUEE（跑马灯模式）时，接口不生效。
- 若 selectionStart >= selectionEnd，视为无效选区。
- 选区最大范围为 ，超出 textSize 的索引会被安全截断。
- 若选区索引处于不可见截断区域（由于滚动或尺寸限制），高亮不会生效。
- PC/2in1 设备上即使设置 MenuPolicy.SHOW，也不会主动弹出二级菜单。
- Emoji 字符被截断时会被作为一个完整单元选中。
- 系统能力：SystemCapability.ArkUI.ArkUI.Full，API 23 起支持元服务调用，覆盖 Phone、PC/2in1、Tablet、TV、Wearable。
三、实战开发步骤
以下是一个完整的示例，展示如何在应用中实现动态选区高亮。首先，在 Text 组件上绑定 TextController 并设置 copyOption：
private textController: TextController = new TextController();
private testTextValue: string = 'HarmonyOS NEXT 极客排版与动态选区高亮技术（API 23）';
// 在 build() 中
Text(this.testTextValue, { controller: this.textController })
.copyOption(CopyOptions.InApp) // 必须配置，否则无效
.fontSize(16)
.fontColor('#FFFFFF')
.lineHeight(24)
.width('100%')
.padding(12)
.backgroundColor('#111111')
.borderRadius(8);
然后，通过按钮触发动态选择：
Button('触发 setTextSelection')
.onClick(() => {
try {
this.textController.setTextSelection(
this.selectionStartInput,
this.selectionEndInput,
{ menuPolicy: MenuPolicy.SHOW }// 显示系统菜单
);
// 更新日志
} catch (err) {
// 异常处理
}
});
清除选区时，传入相等或无效的索引即可：
this.textController.setTextSelection(0, 0); // 起始>=结束，不选中
注意：输入框应绑定状态变量并转为整数，避免非法输入。完整示例中建议添加文本总字符数提示和操作日志输出，便于调试。
四、运行效果与性能
在实测中，输入起始索引 0、结束索引 10，点击触发后，“HarmonyOS ” 瞬间被蓝色半透明高亮覆盖，同时弹出系统原生复制、搜索等菜单，与用户长按效果一致。即使将索引设为超出文本长度（如 999），系统自动截断到末尾，无任何异常。在高频快速点击（30Hz+）时，CPU 占用率极低，无卡顿重排，性能表现出色。
五、避坑指南
1. CopyOptions.None 导致静默失效：忘记设置 copyOption 或误设为 None，setTextSelection() 不会报错但不产生任何效果。务必显式设置为 CopyOptions.InApp 或 CopyOptions.LocalDevice。
2. 不可见截断区域导致“选择哑弹”：如果 Text 组件限制了高度/宽度且使用了 textOverflow 截断，索引指向被截断的不可见字符时，高亮无法生效。解决方案是结合滚动视图（如 Scroll），或者关闭截断（不设 textOverflow），确保所有字符在排版树中可见。
六、总结
setTextSelection() 接口使开发者能够以代码方式精确控制文本选区高亮，并与系统原生菜单联动，为 AI 划词、动态标注、语音阅读同步高亮等场景提供了原生级性能支持。开发者应充分利用 API 23 的这一能力，重构传统通过拆分 Text 组件实现高亮的做法，获得更流畅、更贴近系统体验的交互效果。
Re: HarmonyOS NEXT 6.1 TextController动态高亮选区实战解析
感谢鸿蒙专家的深度解析！这篇实战指南非常清晰，从原理到代码细节都讲得很透彻，尤其是避坑部分——把`copyOption`遗漏和不可见截断区这两个最容易踩的坑点出来，对实际开发帮助很大。 一直很想在文本标注场景里用代码控制选区，之前只能靠拆Text组件模拟，性能确实有瓶颈。`setTextSelection()`直接操作底层选区状态机，加上不触发重排的局部绘制，这个设计思路确实漂亮。想请教一个问题：如果Text组件放在`Scroll`里且内容滚动，调用`setTextSelection()`选中一个当前不可见的索引区间时，组件会自动滚动到对应位置吗？还是需要开发者手动调滚动？Re: HarmonyOS NEXT 6.1 TextController动态高亮选区实战解析
感谢楼主这么详细的解析！我之前在API 23上试过用TextController控制光标位置，但一直没搞懂选区高亮这块，原来关键在`copyOption`和`setTextSelection`的配合。特别是避坑指南里提到的“不可见截断区域导致选择哑弹”这个点，确实容易踩坑——之前就遇到过Text加了`textOverflow`后调用无效，现在终于明白原因了。楼主提到AI划词、语音阅读同步高亮这些场景，感觉正好可以用在阅读器或者笔记类应用里。想问一下，如果我想实现跨段落的连续高亮（比如两段文字中间有`\n`），索引是按字符数连续算还是按段落分开处理？期待楼主后续有没有更多关于多段文本选区的经验分享。Re: HarmonyOS NEXT 6.1 TextController动态高亮选区实战解析
感谢鸿蒙专家的详细解析！之前一直在用拆分Text加背景色模拟高亮，性能确实不太理想，这个新接口直接突破底层选区状态机，思路很清晰。有个疑问想请教：如果文本很长，滚动到了中间部分，然后通过 setTextSelection 选中开头区域的文字，Text组件会自动滚动到选区位置吗？还是需要开发者手动配合 Scroll 或 List 的 scrollToIndex 来确保可见？另外，避坑指南提到不可见截断会导致“选择哑弹”，有没有推荐的最佳实践来动态保证选区的可见性？期待后续更多实战案例。
页:
[1]