HarmonyOS6 ArkTS RichText组件使用文档

文章目录组件概述1 核心作用2 基础使用条件3 基础代码结构可运行示例核心详解1 核心入参HTML格式字符串1.1 支持的核心HTML标签1.2 支持的常用内联CSS样式2 基础样式属性3 核心事件典型应用场景场景1复杂HTML内容解析与渲染场景2Flex布局下的基础富文本展示场景3Flex布局下的权重占比展示代码示例解析常见问题总结问题1RichText组件无任何渲染效果页面仅显示空白问题2HTML中的样式未生效如字体颜色、对齐方式问题3Flex布局中layoutWeight权重配置无效问题4富文本内容溢出组件边界无法完整展示问题5onComplete事件未触发总结组件概述1 核心作用RichText组件用于解析并渲染HTML格式的字符串内容将标准HTML标签及内联样式转换为ArkTS原生的可视化界面支持常见的HTML标签如h1-h3、p、div、hr、i、u等和内联CSS样式如字体、颜色、对齐、背景等实现无需手动布局的富文本展示大幅降低富文本开发成本。2 基础使用条件组件归属HarmonyOS ArkTS 基础富文本组件无需额外导入任何模块直接使用运行环境API Version 14HarmonyOS 6核心版本完善HTML标签和样式解析能力内容格式入参为HTML格式的字符串支持标签嵌套和内联style样式配置布局特性可与Flex、Column、Row等布局组件配合支持尺寸、权重、背景等基础样式配置3 基础代码结构Entry Component struct RichTextBasicDemo { State richTextData: string p stylecolor: 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 styletext-align: center;h1标题/h1 h1 styletext-align: center;ih1斜体/i/h1 h1 styletext-align: center;uh1下划线/u/h1 h2 styletext-align: center;h2标题/h2 h3 styletext-align: center;h3标题/h3 p styletext-align: center;p常规/phr/ div stylewidth: 500px;height: 500px;border: 1px solid;margin: 0 auto; p stylefont-size: 35px;text-align: center;font-weight: bold; color: rgb(24,78,228)字体大小35px,行高45px/p p stylebackground-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标签标签名核心作用示例用法h1/h2/h3标题标签自带默认加粗效果h1字号最大h3最小h1 styletext-align: center;h1标题/h1p段落标签用于包裹常规文本支持多行展示p stylefont-size: 35px;常规段落/pdiv容器标签用于包裹多个子标签支持统一布局配置div stylewidth: 500px; margin: 0 auto;.../divhr分隔线标签实现内容区域的水平分隔hr/i斜体标签将文本设置为斜体样式ih1斜体/iu下划线标签为文本添加下划线uh1下划线/u1.2 支持的常用内联CSS样式样式属性取值范围核心作用示例用法text-alignleft/center/right文本水平对齐方式text-align: centerfont-size数字px如35px设置字体大小font-size: 35pxfont-weightbold/normal设置字体粗细font-weight: boldcolorRGB/十六进制/颜色名设置文本颜色color: rgb(24,78,228)/color: #184EE4background-color十六进制/颜色名设置背景颜色background-color: #e5e5e5line-height数字px如45px设置文本行高line-height: 45pxtext-indent数字em如2em设置段落首行缩进2em为两个字符宽度text-indent: 2emwidth/height数字px设置容器宽度/高度width: 500px; height: 500pxborder边框样式如1px solid为容器添加边框border: 1px solidmargin数字px/auto设置外边距margin: 0 auto实现水平居中margin: 0 auto2 基础样式属性RichText支持ArkTS通用的基础样式属性用于配置组件自身的尺寸、背景、布局等与普通布局组件用法一致示例中全覆盖核心样式属性属性名配置方式核心作用示例配置width/height数字/百分比/size({width, height})设置组件宽高.width(500)/.size({width: 100%, height: 110})backgroundColor十六进制/Color枚举/RGB设置组件背景色.backgroundColor(0XBDDB69)layoutWeight数字配合Flex布局设置组件占父容器的权重比例.layoutWeight(1)3 核心事件RichText提供两个生命周期事件用于监听富文本的解析和渲染过程方便开发者在对应阶段执行逻辑处理如加载状态提示、渲染完成后的后续操作示例中均已配置事件名回调函数触发时机核心作用onStart() void组件开始解析HTML内容时触发监听富文本解析开始可显示加载提示onComplete() void组件完成HTML解析并渲染完成时触发监听富文本渲染完成可隐藏加载提示、执行后续逻辑示例配置方式RichText(this.data) .onStart(() { console.info(RichText onStart); // 解析开始时打印日志 }) .onComplete(() { console.info(RichText onComplete); // 渲染完成时打印日志 });典型应用场景场景1复杂HTML内容解析与渲染实现要点通过State定义HTML格式的字符串变量data整合h1-h3标题、p段落、i/u格式化标签、hr分隔线、div容器标签为不同标签配置个性化内联样式标题居中、段落设置字体大小/颜色/行高/首行缩进、div容器固定宽高边框水平居中为RichText设置固定宽高和背景色保证富文本内容的展示区域固定。核心代码片段State data: string h1 styletext-align: center;h1标题/h1 h1 styletext-align: center;ih1斜体/i/h1 div stylewidth: 500px;height: 500px;border: 1px solid;margin: 0 auto; p stylefont-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); });场景2Flex布局下的基础富文本展示核心需求在Flex布局中实现简单富文本内容的展示配置组件100%宽度、固定高度和背景色适用于导航栏说明、简单提示语等轻量富文本场景。实现要点RichText入参为简单文本字符串无需复杂HTML标签通过size({ width: 100%, height: 110 })设置组件自适应父容器宽度、固定高度配置背景色提升界面视觉区分度。核心代码片段RichText(layoutWeight(1)) .size({ width: 100%, height: 110 }) .backgroundColor(0X92D6CC) .onStart(() { console.info(RichText onStart); }) .onComplete(() { console.info(RichText onComplete); });场景3Flex布局下的权重占比展示核心需求在Flex布局中通过layoutWeight属性设置多个RichText组件的占比比例实现父容器空间的按权重分配适用于多区域富文本分栏展示、底部多富文本提示等场景。实现要点多个RichText组件同级放置在Flex容器中均设置width: 100%和固定高度分别配置layoutWeight(1)和layoutWeight(2)实现两个组件在Flex容器中按1:2的比例分配剩余空间为不同组件设置不同背景色直观展示权重占比效果。核心代码片段// 权重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无额外子组件结构简洁清晰可直接运行整体结构如下状态变量定义State data变量存储复杂HTML格式的富文本字符串整合多种标签和样式根布局使用Flex作为页面根布局配置direction: FlexDirection.Column垂直布局、alignItems: ItemAlign.Center子组件水平居中、justifyContent: FlexAlign.Center子组件垂直居中实现页面整体居中效果核心组件三个RichText组件依次排列分别实现复杂HTML解析、基础Flex布局展示、权重占比展示三大场景统一配置所有RichText组件均配置onStart和onComplete事件监听解析和渲染过程同时配置个性化的尺寸、背景、权重属性。常见问题总结问题1RichText组件无任何渲染效果页面仅显示空白排查点1确认入参为合法的HTML格式字符串避免字符串为空或格式错误如标签未闭合、样式属性缺少冒号/分号排查点2确认使用的HTML标签为HarmonyOS支持的核心标签未使用form、img等未支持标签排查点3确认RichText组件设置了有效宽高未设置宽高会导致组件尺寸为0无法显示内容。问题2HTML中的样式未生效如字体颜色、对齐方式排查点1确认样式配置在内联style属性中未使用外部CSS或内部style标签排查点2确认样式属性名和取值符合规范如text-align而非textAlign颜色值带#或rgb()字体大小带px排查点3确认样式作用的标签为HarmonyOS支持的标签部分样式仅对特定标签生效如text-indent仅对p标签生效。问题3Flex布局中layoutWeight权重配置无效排查点1确认RichText的父容器为Flex布局非Column/Row等其他布局排查点2确认RichText的宽度设置为100%或未设置固定宽度固定宽度会导致权重分配失效排查点3确认同级的其他Flex子组件也配置了layoutWeight或父容器有剩余空间可分配。问题4富文本内容溢出组件边界无法完整展示排查点1确认RichText组件的宽高大于等于HTML内容中容器的宽高避免内容超出组件范围排查点2若HTML内容为动态加载可在onComplete事件中获取组件实际渲染高度动态调整RichText的高度排查点3移除HTML内容中不必要的固定宽高设置让内容自适应RichText组件的尺寸。问题5onComplete事件未触发排查点1确认HTML字符串格式合法解析过程无错误解析失败会导致onComplete无法触发排查点2确认RichText组件已被正确渲染到页面中未被其他组件遮挡或未加入布局树排查点3确认项目编译版本为API 14低版本对部分HTML标签解析支持不佳可能导致解析流程中断。总结RichText是HarmonyOS 6 ArkTS中实现富文本展示的核心组件通过解析HTML格式字符串快速实现多样化的富文本渲染效果无需手动通过Span、Text等组件拼接布局大幅提升富文本开发效率。该组件支持核心HTML标签和常用内联CSS样式可与Flex等布局组件灵活配合同时提供解析和渲染的生命周期事件满足从简单提示到复杂文章详情的各类富文本展示需求。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力