HarmonyOS6 ArkTS RichText组件使用文档

组件概述

1 核心作用

RichText组件用于解析并渲染HTML格式的字符串内容，将标准HTML标签及内联样式转换为ArkTS原生的可视化界面，支持常见的HTML标签（如h1-h3、p、div、hr、i、u等）和内联CSS样式（如字体、颜色、对齐、背景等），实现无需手动布局的富文本展示，大幅降低富文本开发成本。

2 基础使用条件

• 组件归属：HarmonyOS ArkTS 基础富文本组件，无需额外导入任何模块，直接使用
• 运行环境：API Version 14+（HarmonyOS 6核心版本，完善HTML标签和样式解析能力）
• 内容格式：入参为HTML格式的字符串，支持标签嵌套和内联style样式配置
• 布局特性：可与Flex、Column、Row等布局组件配合，支持尺寸、权重、背景等基础样式配置

3 基础代码结构

@Entry @Component struct RichTextBasicDemo { @State richTextData: string = '<p style="color: blue; text-align: center;">基础富文本展示</p>'; build() { Column() { // 核心用法：传入HTML格式字符串 RichText(this.richTextData) .width('90%') .backgroundColor('#f5f5f5'); } } }

可运行示例

// xxx.ets @Entry @Component struct RichTextExample { @State data: string = '<h1 style="text-align: center;">h1标题</h1>' + '<h1 style="text-align: center;"><i>h1斜体</i></h1>' + '<h1 style="text-align: center;"><u>h1下划线</u></h1>' + '<h2 style="text-align: center;">h2标题</h2>' + '<h3 style="text-align: center;">h3标题</h3>' + '<p style="text-align: center;">p常规</p><hr/>' + '<div style="width: 500px;height: 500px;border: 1px solid;margin: 0 auto;">' + '<p style="font-size: 35px;text-align: center;font-weight: bold; color: rgb(24,78,228)">字体大小35px,行高45px</p>' + '<p style="background-color: #e5e5e5;line-height: 45px;font-size: 35px;text-indent: 2em;">' + '<p>这是一段文字这是一段文字这是一段文字这是一段文字这是一段文字这是一段文字这是一段文字这是一段文字这是一段文字</p>'; build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { RichText(this.data) .onStart(() => { console.info('RichText onStart'); }) .onComplete(() => { console.info('RichText onComplete'); }) .width(500) .height(500) .backgroundColor(0XBDDB69) RichText('layoutWeight(1)') .onStart(() => { console.info('RichText onStart'); }) .onComplete(() => { console.info('RichText onComplete'); }) .size({ width: '100%', height: 110 }) .backgroundColor(0X92D6CC) .layoutWeight(1) RichText('layoutWeight(2)') .onStart(() => { console.info('RichText onStart'); }) .onComplete(() => { console.info('RichText onComplete'); }) .size({ width: '100%', height: 110 }) .backgroundColor(0X92C48D) .layoutWeight(2) } } }

运行效果如图：

核心详解

1 核心入参：HTML格式字符串

RichText的构造函数唯一入参为HTML格式的字符串，组件会自动解析字符串中的HTML标签和内联style样式，并转换为原生渲染效果。示例中覆盖了HarmonyOS 6支持的核心HTML标签和常用内联样式，是实际开发中最常用的配置方式。

1.1 支持的核心HTML标签

1.2 支持的常用内联CSS样式

2 基础样式属性

RichText支持ArkTS通用的基础样式属性，用于配置组件自身的尺寸、背景、布局等，与普通布局组件用法一致，示例中全覆盖核心样式属性：

3 核心事件

RichText提供两个生命周期事件，用于监听富文本的解析和渲染过程，方便开发者在对应阶段执行逻辑处理（如加载状态提示、渲染完成后的后续操作），示例中均已配置：

示例配置方式：

RichText(this.data) .onStart(() => { console.info('RichText onStart'); // 解析开始时打印日志 }) .onComplete(() => { console.info('RichText onComplete'); // 渲染完成时打印日志 });

典型应用场景

场景1：复杂HTML内容解析与渲染

实现要点：

1. 通过@State定义HTML格式的字符串变量data，整合h1-h3标题、p段落、i/u格式化标签、hr分隔线、div容器标签；
2. 为不同标签配置个性化内联样式：标题居中、段落设置字体大小/颜色/行高/首行缩进、div容器固定宽高+边框+水平居中；
3. 为RichText设置固定宽高和背景色，保证富文本内容的展示区域固定。
   核心代码片段：

@State data: string = '<h1 style="text-align: center;">h1标题</h1>' + '<h1 style="text-align: center;"><i>h1斜体</i></h1>' + '<div style="width: 500px;height: 500px;border: 1px solid;margin: 0 auto;">' + '<p style="font-size: 35px;text-align: center;font-weight: bold; color: rgb(24,78,228)">字体大小35px,行高45px</p>' + '</div>'; // 渲染复杂HTML内容 RichText(this.data) .width(500) .height(500) .backgroundColor(0XBDDB69) .onStart(() => { console.info('RichText onStart'); }) .onComplete(() => { console.info('RichText onComplete'); });

场景2：Flex布局下的基础富文本展示

核心需求：在Flex布局中实现简单富文本内容的展示，配置组件100%宽度、固定高度和背景色，适用于导航栏说明、简单提示语等轻量富文本场景。
实现要点：

1. RichText入参为简单文本字符串，无需复杂HTML标签；
2. 通过size({ width: '100%', height: 110 })设置组件自适应父容器宽度、固定高度；
3. 配置背景色，提升界面视觉区分度。
   核心代码片段：

RichText('layoutWeight(1)') .size({ width: '100%', height: 110 }) .backgroundColor(0X92D6CC) .onStart(() => { console.info('RichText onStart'); }) .onComplete(() => { console.info('RichText onComplete'); });

场景3：Flex布局下的权重占比展示

核心需求：在Flex布局中，通过layoutWeight属性设置多个RichText组件的占比比例，实现父容器空间的按权重分配，适用于多区域富文本分栏展示、底部多富文本提示等场景。
实现要点：

1. 多个RichText组件同级放置在Flex容器中，均设置width: 100%和固定高度；
2. 分别配置layoutWeight(1)和layoutWeight(2)，实现两个组件在Flex容器中按1:2的比例分配剩余空间；
3. 为不同组件设置不同背景色，直观展示权重占比效果。
   核心代码片段：

// 权重1，占父容器1/3空间 RichText('layoutWeight(1)') .size({ width: '100%', height: 110 }) .backgroundColor(0X92D6CC) .layoutWeight(1); // 权重2，占父容器2/3空间 RichText('layoutWeight(2)') .size({ width: '100%', height: 110 }) .backgroundColor(0X92C48D) .layoutWeight(2);

代码示例解析

配套代码为一个完整的@Entry组件RichTextExample，无额外子组件，结构简洁清晰，可直接运行，整体结构如下：

1. 状态变量：定义@State data变量，存储复杂HTML格式的富文本字符串，整合多种标签和样式；
2. 根布局：使用Flex作为页面根布局，配置direction: FlexDirection.Column（垂直布局）、alignItems: ItemAlign.Center（子组件水平居中）、justifyContent: FlexAlign.Center（子组件垂直居中），实现页面整体居中效果；
3. 核心组件：三个RichText组件依次排列，分别实现复杂HTML解析、基础Flex布局展示、权重占比展示三大场景；
4. 统一配置：所有RichText组件均配置onStart和onComplete事件，监听解析和渲染过程，同时配置个性化的尺寸、背景、权重属性。

常见问题总结

问题1：RichText组件无任何渲染效果，页面仅显示空白

• 排查点1：确认入参为合法的HTML格式字符串，避免字符串为空或格式错误（如标签未闭合、样式属性缺少冒号/分号）；
• 排查点2：确认使用的HTML标签为HarmonyOS支持的核心标签，未使用form、img等未支持标签；
• 排查点3：确认RichText组件设置了有效宽高，未设置宽高会导致组件尺寸为0，无法显示内容。

问题2：HTML中的样式未生效（如字体颜色、对齐方式）

• 排查点1：确认样式配置在内联style属性中，未使用外部CSS或内部style标签；
• 排查点2：确认样式属性名和取值符合规范（如text-align而非textAlign，颜色值带#或rgb()，字体大小带px）；
• 排查点3：确认样式作用的标签为HarmonyOS支持的标签，部分样式仅对特定标签生效（如text-indent仅对p标签生效）。

问题3：Flex布局中layoutWeight权重配置无效

• 排查点1：确认RichText的父容器为Flex布局，非Column/Row等其他布局；
• 排查点2：确认RichText的宽度设置为100%或未设置固定宽度，固定宽度会导致权重分配失效；
• 排查点3：确认同级的其他Flex子组件也配置了layoutWeight，或父容器有剩余空间可分配。

问题4：富文本内容溢出组件边界，无法完整展示

• 排查点1：确认RichText组件的宽高大于等于HTML内容中容器的宽高，避免内容超出组件范围；
• 排查点2：若HTML内容为动态加载，可在onComplete事件中获取组件实际渲染高度，动态调整RichText的高度；
• 排查点3：移除HTML内容中不必要的固定宽高设置，让内容自适应RichText组件的尺寸。

问题5：onComplete事件未触发

• 排查点1：确认HTML字符串格式合法，解析过程无错误，解析失败会导致onComplete无法触发；
• 排查点2：确认RichText组件已被正确渲染到页面中，未被其他组件遮挡或未加入布局树；
• 排查点3：确认项目编译版本为API 14+，低版本对部分HTML标签解析支持不佳，可能导致解析流程中断。

总结

RichText是HarmonyOS 6 ArkTS中实现富文本展示的核心组件，通过解析HTML格式字符串，快速实现多样化的富文本渲染效果，无需手动通过Span、Text等组件拼接布局，大幅提升富文本开发效率。该组件支持核心HTML标签和常用内联CSS样式，可与Flex等布局组件灵活配合，同时提供解析和渲染的生命周期事件，满足从简单提示到复杂文章详情的各类富文本展示需求。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力