鸿蒙 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 承载。

热心网友5

楼主这篇总结得很实用，尤其是 native 和 web 的选择原则。我们这边也是简单文章 native 够用，商品详情一有 div、table、video 就不行，切 web 最稳。native 下 font-size、margin、padding 不生效和图片不自适应这两个坑很深，给 img 加 width 100% 后好一些。链接不会自动跳转也遇到过，监听 itemclick 再自己处理确实有必要。视频和 iframe 现在都在预处理阶段替换成文字提示，复杂页面直接 WebView 承载。引号转义那个细节也很有用，单双引号混用容易导致整个 HTML 字符串解析异常。感谢分享，收藏了。

热心网友1

感谢楼主整理，内容很实用。我的理解是：rich-text 在鸿蒙 uni-app x 里就是渲染 HTML 的主要方案，但 native 和 web 的取舍非常关键。简单文章、活动说明可以用 native 换性能和内存；商品详情、带表格或视频或 iframe、样式复杂的，直接上 web 更稳。几个坑也记下了：native 不支持 div、table、video、iframe，font-size、margin、padding 等样式也不生效；图片要设 width 为 100%；链接必须自己监听 @itemclick 取 href 再跳转；视频和 iframe 最好在 computed 里预处理成占位文字；还有引号转义容易导致模板解析错误。整体上，我觉得先按内容复杂度选模式，native 渲染不对就及时切 web，复杂页面直接用 WebView 承载，这个思路很清晰。

热心网友1

楼主总结得很到位，收藏了。我们在鸿蒙 uni-app x 里也遇到过 rich-text 的坑：native 模式下图片宽度确实容易出问题，给 img 加上 width 100% 后好一些；超链接不自动跳转也很容易忽略，必须自己监听 itemclick 再处理。现在看你的清单，div、table、video、iframe 不支持这点最关键，复杂详情页直接上 web 模式省心很多。后端预处理 HTML 的思路也实用，尤其是把 video、iframe 替换成文字占位，避免渲染空白。感谢分享，后面遇到 native 样式不生效就按这个思路先排查再切 web。