鸿蒙 uni-app x rich-text 渲染模式选择与避坑

鸿蒙专家

背景：在 uni-app x 鸿蒙端，后端返回的商品详情、文章内容、活动说明常常是 HTML 字符串，rich-text 组件负责把这些 HTML 渲染成原生组件。HarmonyOS 4.61 开始支持该组件。结论先说：简单 HTML 可以优先 native，复杂 HTML 慎用 native，必要时切 web 模式。

一、基础用法
rich-text 支持两种 nodes 传值方式：传 HTML 字符串，或传节点数组。大多数业务用 HTML 字符串即可。节点数组适合需要精确控制节点属性的场景，节点类型可包含 name、attrs、children、text。

2. <rich-text :nodes='htmlContent' mode='native'></rich-text>

复制代码

二、web 与 native 怎么选
web 模式默认使用 WebView 渲染，支持更多 HTML 标签，但性能一般、内存占用大。native 模式使用原生组件渲染，性能好、内存占用小，但支持标签和样式有限。选择原则：简单内容用 native，复杂内容用 web；如果 native 渲染样式不对，换 web 排查。

2. <rich-text :nodes='htmlContent' mode='web'></rich-text>
3. <rich-text :nodes='htmlContent' mode='native'></rich-text>

复制代码

三、native 模式的标签与样式边界
native 模式可用的标签主要包括 p、span、strong、i、a、img、ul、li、h1-h6、br、u、del。div 不在支持列表，table、video、iframe 也不支持。样式方面，native 模式可用 text-align、color、background-color、text-decoration（仅 line-through），font-size、margin、padding 等常用样式不支持。需要复杂样式时，优先换 web 模式，或改用节点数组在 attrs 中设置 style。

四、实战建议
1. 带图片：商品详情通常有图片，web 模式更稳定；native 模式下图片可能显示不全。若必须 native，可在 HTML 中给图片设置 width='100%'。
2. 带链接：rich-text 中的超链接不会自动跳转，需要监听 @itemclick，自行取 event.detail.href 并用 uni.navigateTo 打开内部 webview 页面。

2. <rich-text :nodes='html' mode='web' @itemclick='onItemClick'></rich-text>

复制代码

3. 可选文本：给 rich-text 加 :selectable='true'，用户可长按选中复制内容。
4. 后端 HTML 预处理：实际项目可在 computed 中对原始 HTML 做替换，例如给 img 增加 max-width: 100%; height: auto;，把 video 替换为 [视频]，把 iframe 替换为 [嵌入内容]。

五、鸿蒙平台注意点
HarmonyOS 4.61 起支持 rich-text。鸿蒙原生开发没有直接等价的富文本渲染组件，通常要用 Web 组件加载 HTML，或者用 Text + Span 组合实现；uni-app x 的 rich-text 把这一步封装掉了。

2. Web({ src: '', controller: this.webController })
3.   .javaScriptAccess(true)
4.   .onPageEnd(() => {
5.     this.webController.loadHtml(htmlContent)
6.   })

复制代码

六、踩坑清单
- native 标签少：div、table、video、iframe 渲染不了，换 web 或预处理。
- native 样式少：font-size、margin、padding 等不生效，换 web 或用节点数组 attrs。
- 图片宽度：native 下可能不自适应，给 img 设置 width='100%'。
- 链接点击：必须自己监听 @itemclick 并处理跳转。
- video/iframe：rich-text 不支持，需预处理替换。
- 嵌套组件：rich-text 内不能放其他组件，复杂布局用 scroll-view + 多个组件组合。
- 引号转义：HTML 字符串属性值用双引号时，nodes 整体用单引号，或反过来，避免模板解析错误。

总结：rich-text 是 uni-app x 中渲染 HTML 内容的唯一方案。它适合商品详情、文章内容等大多数场景，但能力有限。简单 HTML 用 native，复杂 HTML 用 web；遇到 native 样式和标签不满足时，及时切换渲染模式或预处理 HTML。对于视频、表格、自定义样式很多的页面，考虑直接用 WebView 承载。