HarmonyOS 鸿蒙Next中富文本内容处理

HarmonyOS 鸿蒙Next中富文本内容处理 富文本用什么控件处理？文档上有处理富文的Api或者示例吗？

5 回复

开发者你好，ArkUI提供了RichEditor组件，支持图文混排和交互式文本编辑。

【解决方案】

  • RichEditor：是支持图文混排和文本交互式编辑的组件，通常用于响应用户对图文混合内容的输入操作，例如可以输入图文的评论区。具体用法参考RichEditor富文本编辑。

实现原理

RichEditor组件内容管理方式选型

RichEditor组件提供两套内容管理接口，方式一使用RichEditor(options: RichEditorStyledStringOptions)接口创建基于属性字符串（StyledString/MutableStyledString）进行内容管理的组件，方式二使用RichEditor(value: RichEditorOptions)接口创建基于Span进行内容管理的组件。在本文内容发布场景中需要频繁进行输入文字、添加表情、@好友、删除等操作，且无需复杂的样式操作，选择使用方式二基于Span进行内容管理更为合适。

  • 方式一：基于属性字符串管理
    • 进行内容样式更新，更加灵活便捷。
    • 序列化困难，需手动提取属性存储，增加持久化逻辑复杂度。
    • 动态内容维护成本高，不适合频繁增删操作。
  • 方式二：基于Span管理
    • 使用便捷，通过直接操作独立的Span来动态构建和修改内容。
    • 支持增量式操作，适合需要频繁交互、动态修改（如插入表情、@好友）的场景。

添加不同类型内容的方式选型

编辑区域支持输入文字、表情、@好友等内容。

使用addBuilderSpan()方法 使用addTextSpan()方法
内容长度 默认作为一个整体，长度视为一个文字 以文本形式添加，长度为文本长度
光标与删除逻辑 默认作为一个整体，无需额外处理 需手动处理光标变化、删除规则
折行与显示规则 长度超一行：光标高度随builderSpan高度自动调整
长度不超一行：无法折行，触达边界后自动换行		 与普通文本逻辑一致，支持正常折行显示
数据获取与维护 无法获取builderSpan中的内容 可获取textSpan内容，但额外携带数据需自行维护

更多关于HarmonyOS 鸿蒙Next中富文本内容处理的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


富文本编辑（RichEditor）

RichEditor是支持图文混排和文本交互式编辑的组件，通常用于响应用户对图文混合内容的输入操作，例如可以输入图文的评论区。具体用法参考RichEditor。

对于仅需图文展示而不需要编辑的场景，推荐使用Text组件。

对于需要大量展示Html格式内容的场景，推荐使用RichText组件。

组件构成

下图展示了组件元素的构成。

图片

组件的元素构成包括：

元素 说明
内容区 内容可显示的区域。
光标 用于指明当前输入位置。
手柄 分为左手柄和右手柄，可分别进行拖动，用于调整文本选择区域范围。
菜单 选中内容后弹出，其中包含复制、粘贴等内容操作按钮。

示例代码：

@Entry
@Component
struct add_text_span {
  controller: RichEditorController = new RichEditorController();
  options: RichEditorOptions = { controller: this.controller };
  build() {
    Column() {
      RichEditor(this.options)
        .onReady(() => {
          this.controller.addTextSpan('点击按钮在此处添加text。', {
            style: {
              fontColor: Color.Black,
              fontSize: 15
            }
          })
        })
        .border({ width: 1, color: Color.Gray })
        .constraintSize({
          maxHeight: 100
        })
        .width(300)
        .margin(10)
      Button('addTextSpan', {
        buttonStyle: ButtonStyleMode.NORMAL
      })
        .height(30)
        .fontSize(13)
        .onClick(() => {
          this.controller.addTextSpan('新添加一段文字。')
        })
    }
  }
}

官方文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-common-components-richeditor

【问题背景】

  • 想用富文本进行业务开发，请问使用哪些方法可以实现，官网的富文本开发示例文档在哪？

【解决思路】

【官方文档——富文本组件说明及示例】

1. 确定核心处理控件：RichEditor

HarmonyOS ArkUI 框架中，专门用于富文本处理的控件为RichEditor，其核心定位是 “支持图文混排与交互式编辑”，从 API version 10 开始提供支持，后续版本（如 12+、20+）持续新增功能（如属性字符串适配、中文西文自动间距），且全量支持 Phone/PC/2in1/Tablet/TV/Wearable 设备。

2. 文档中的 API 支持（核心能力拆解）

文档中围绕 RichEditor 提供了完整的 API 体系，涵盖初始化、属性配置、事件监听、数据交互等全流程：

  • 初始化接口：提供 2 类初始化方式，适配不同场景 ——
    • API 10 + 基础初始化：RichEditor(value: RichEditorOptions)，需传入RichEditorController（用于后续添加 / 删除 / 更新内容）；
    • API 12 + 属性字符串初始化：RichEditor(options: RichEditorStyledStringOptions)，搭配RichEditorStyledStringController，支持样式与内容分离管理。
  • 关键属性：覆盖交互、样式、内容限制等需求，例如 ——
    • 交互类：customKeyboard（自定义键盘）、bindSelectionMenu（自定义选中菜单）、enableDataDetector（文本实体识别，如链接 / 手机号）；
    • 样式类：caretColor（光标颜色）、selectedBackgroundColor（选中背景色）、placeholder（无输入提示）；
    • 限制类：maxLength（内容最大长度）、maxLines（最大显示行数）。
  • 核心事件：监听富文本编辑全生命周期，例如 ——
    • 内容变化：onWillChange（增删前拦截）、onDidChange（增删后回调）；
    • 交互触发：onPaste（粘贴拦截）、onSelect（选中回调）、onSubmit（回车键触发）；
    • 状态变化：onEditingChange（编辑态 / 非编辑态切换）。
  • 控制器能力：通过RichEditorController/RichEditorStyledStringController实现内容操作，例如 ——
    • 添加内容：addTextSpan（文本）、addImageSpan（图片）、addBuilderSpan（自定义布局）；
    • 样式更新：updateSpanStyle（文本 / 图片样式修改）、updateParagraphStyle（段落样式调整）；
    • 内容管理：deleteSpans（删除指定范围内容）、getSpans（获取 Span 信息）。

3. 文档中的实操示例

典型示例，覆盖富文本核心使用场景，按功能可分为 4 类：

  • 样式操作类：如 “更新文本加粗样式”“设置图片圆角与外边距”“添加多重文本阴影”；
  • 交互功能类：如 “自定义数字键盘”“长按弹出自定义复制菜单”“拦截粘贴并自定义图文粘贴逻辑”；
  • 内容管理类：如 “添加自定义布局（BuilderSpan）”“限制内容最大长度与显示行数”“通过属性字符串绑定富文本内容”；
  • 特色功能类：如 “开启文本实体识别（识别手机号并弹出拨号菜单）”“获取光标坐标”“撤销时保留原样式”。

三、使用场景

RichEditor 控件适用于 HarmonyOS 全设备中需富文本交互的场景，典型包括：

  1. 社交类应用：如朋友圈 / 动态发布（需图文混排，用addTextSpan+addImageSpan）、评论编辑（需快速插入表情 / Symbol，用addSymbolSpan）；
  2. 办公类应用：如简易文档编辑器（需段落样式调整，用updateParagraphStyle）、邮件撰写（需限制内容长度，用maxLength）、笔记应用（需预上屏预览，用enablePreviewText）；
  3. 教育类应用：如课件编辑（需插入自定义教学组件，用addBuilderSpan）、作业批注（需文本选中后弹出批注菜单，用bindSelectionMenu）；
  4. 元服务场景：如轻量图文卡片编辑（API 11 + 支持元服务，用RichEditorStyledStringController实现轻量化样式管理）、设备端简易笔记（需触感反馈，用enableHapticFeedback）。

【官方文档——富文本组件使用指南】

鸿蒙Next的富文本处理基于ArkUI框架，通过Text组件和Span组件实现。支持设置字体样式、颜色、大小、背景色及点击事件。可使用@State装饰器动态更新富文本内容。提供TextDecorationType枚举设置下划线、删除线等装饰效果。通过ResourceStrBuilder构建包含多段样式的字符串，实现图文混排。支持自定义字体加载和文本超链接识别。文本布局支持弹性换行和裁剪策略，可通过textOverflow属性控制溢出行为。

在HarmonyOS Next中，处理富文本内容推荐使用RichText组件，它支持解析和渲染包含多种样式（如加粗、斜体、颜色、超链接等）的HTML格式文本。开发者可通过设置content属性直接传入富文本字符串，例如：

RichText({ content: '<b>加粗文本</b> 和 <i>斜体文本</i>' })

目前官方文档中提供了RichText组件的详细API说明，包括属性设置和事件处理。示例代码可参考ArkTS API参考文档的“通用组件”部分，其中展示了富文本的基础用法和样式自定义方式。

回到顶部