摆脱WebView！自研鸿蒙NEXT纯原生HTML富文本组件，开箱即用

开源地址

OHPM：https://ohpm.openharmony.cn/#/cn/detail/htmlrichtext

GitHub：https://github.com/oldwounds2120/html-rich-text

适配版本：HarmonyOS NEXT API 12+

开源协议：Apache-2.0（完全免费、支持商用）

官方文档网站：https://www.htmlrichtext.com

当前版本：V1.0.2

工程规范：标准OHPM HAR库、91条全覆盖单元测试

当前版本：V1.0.1

工程规范：标准OHPM HAR库、53条全覆盖单元测试

一、鸿蒙富文本终极痛点！告别卡顿与样式翻车，原生解决方案来了

做 HarmonyOS NEXT 开发的小伙伴，大概率都被 HTML 富文本渲染 坑过！开发资讯详情、帮助文档、技术笔记、用户协议等页面时，后端返回的标准HTML内容，在鸿蒙端始终无法完美落地，官方两套方案各有硬伤，要么卡顿臃肿，要么功能残缺，根本无法满足正式上线需求。

市面上仅有的两种官方渲染方案，早已跟不上业务开发需求，也是无数鸿蒙开发者的共性痛点：

❌ Web 组件

体积臃肿、加载慢、滑动卡顿、原生交互割裂、无法和 App 主题样式统一，为了一段文章引入整个浏览器内核，性价比极低。

❌ 系统原生 RichText

样式完全锁死，无法自定义行高、字间距、段落间距；不支持图片全屏预览、手势缩放，代码块、合并表格、嵌套列表等复杂标签直接渲染失效，但凡复杂一点的文章内容，都会出现样式错乱、内容丢失问题，完全撑不起商业化项目。

为了彻底解决鸿蒙富文本渲染的行业痛点，我从零自研开发了 htmlrichtext 纯原生富文本组件，彻底抛弃WebView和系统原生RichText依赖，手写轻量化HTML解析器，全程基于ArkUI原生组件渲染。

零冗余、高性能、全能力开箱即用，完美适配所有资讯、文档类业务场景，不用重复造轮子、无需二次封装，一行代码即可实现企业级富文本渲染效果，是目前鸿蒙NEXT最实用的原生HTML富文本解决方案！

二、组件核心优势：为什么推荐你直接用它？

100% 纯原生渲染，性能拉满

不依赖任何 Web 内核，摒弃所有冗余能力，通过自研解析器将 HTML 标签精准映射为 Text、Span、Image、Flex、Grid 等标准 ArkUI 原生组件。渲染高效、滑动流畅、适配鸿蒙原生交互逻辑，和普通页面性能完全一致。

业务能力全覆盖，无需二次封装

这是本组件最大的亮点——聚焦真实业务场景，把所有高频刚需能力全部内置，开发者接入即可直接上线：

✅ 完整标签支持：h1~h6 标题、段落、加粗、斜体、删除线、引用、分割线

✅ 图文混排：图片自适应铺满、比例缩放、自动适配屏幕

✅ 完整列表能力：支持 ul/ol 嵌套列表，样式原生规整

✅ 专业表格渲染：支持 table 表格、单元格合并、表头样式、边框完整展示

✅ 技术文档专属：pre/code 代码块语法高亮 + 横向滚动

极致图片交互体验

彻底解决原生组件图片能力缺失的问题：

✅ 点击图片自动唤起全屏预览弹窗

✅ 支持左右滑动切换、双击缩放、手势缩放

✅ 支持 baseUrl 统一处理图片相对路径

✅ 内置图片加载失败回调，可自定义占位处理

全局统一样式配置，一键换肤

通过 RichTextConfig 集中管理所有样式，无需逐行写内联样式，全局文章风格统一管控：

可自定义：正文字号、行高、段间距、标题梯度字号、链接颜色、代码块背景、图片圆角等所有样式。

安全容错，企业级可用

✅ 自动补全未闭合标签、过滤多余闭合标签

✅ 自动跳过 script、style 危险标签内容

✅ 内置 javascript 伪协议拦截，规避 XSS 注入风险

✅ 完整 HTML 实体字符解析，兼容后端不规范返回数据

稳定可靠，有单测保障

组件核心解析、渲染树构建、代码高亮等纯逻辑层代码完全解耦，无ArkUI依赖，支持独立单元测试，目前已完成91条全覆盖单元测试，大幅提升解析容错性与渲染稳定性，可精准校验标签解析、样式继承、特殊字符适配、表格合并、异常容错等各类场景，彻底规避线上解析报错、样式错乱问题，企业级稳定性拉满。同时项目采用标准OHPM HAR工程结构，规范整洁、可直接打包发布，工程化程度极高，详细API与使用教程可查阅官方网站。

三、适配兼容与工程架构解析

✅ 精准版本适配

组件最低适配 HarmonyOS NEXT API 12+，完美适配新版ArkTS语法特性。同时预留API11兼容方案，仅需一行代码微调即可向下兼容旧版本工程，适配绝大多数鸿蒙项目开发场景。

✅ 分层架构设计（高内聚、低耦合）

项目采用逻辑层与UI层完全分离的架构设计，结构清晰、支持二次深度开发：

核心逻辑层：自研HTML解析器、渲染树构建器、数据模型、样式配置器、代码高亮工具，纯TS逻辑，无UI依赖，可独立单测、复用性极强
UI组件层：主渲染组件、全屏图片预览弹窗，专注原生交互与页面渲染
配置层：统一RichTextConfig配置入口，全局样式一键统一管控
使用者无需关注工程构建配置，仅需引入组件即可使用；开发者可基于源码自由拓展自定义标签、专属样式与交互逻辑。

四、快速接入：两种方式，极简使用

方式一：OHPM 一键安装（推荐）

ohpm i htmlrichtext
或在 oh-package.json5 中手动引入依赖后执行安装。

方式二：源码直接引入

将 htmlrichtext 完整目录复制到工程 ets 目录下，本地直接导入使用，无任何依赖、无网络限制。

五、完整使用示例（可直接复制运行）

import { HtmlRichText, RichTextConfig } from 'htmlrichtext';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct ArticlePage {
  // 后端返回的HTML富文本字符串
  @State html: string = `
<h2>鸿蒙原生富文本测试标题</h2>
<p>这是正文内容，支持<strong>加粗文字</strong>、<em>斜体文字</em>、<del>删除文字</del></p>
<blockquote>这是引用文本区块</blockquote>
<pre><code>const app = "鸿蒙富文本组件";</code></pre>
<ul>
  <li>功能开箱即用</li>
  <li>纯原生高性能渲染</li>
</ul>
`;

  // 全局统一样式配置
  private config: RichTextConfig = new RichTextConfig();

  build() {
    Scroll() {
      Column() {
        HtmlRichText({
          html: this.html,
          config: this.config,
          baseUrl: 'https://cdn.example.com',
          // 链接点击回调
          onLinkClick: (url: string) => {
            const context = getContext(this) as common.UIAbilityContext;
            context.openLink(url);
          },
          // 图片点击回调
          onImageClick: (index: number, url: string) => {
            console.log('点击图片：', index, url);
          },
          // 图片加载失败回调
          onImageLoadError: (url: string) => {
            console.log('图片加载失败：', url);
          }
        })
      }
      .width('100%')
      .padding(16)
    }
  }
}

六、支持能力一览

🏷️ 全覆盖HTML标签

标题、段落、文本修饰、超链接、图片、嵌套列表、表格、引用、代码块、分割线等业务常用标签全部支持。

🎨 内联CSS样式支持

支持字体颜色、字号、字重、行高、间距、对齐、圆角、背景色、宽高等常用内联样式解析渲染。

💡 内置专属能力

图片全屏预览缩放、代码语法高亮、表格合并渲染、URL安全拦截、HTML容错解析。

七、适用业务场景

资讯类 App 文章详情页
应用内置帮助中心、FAQ、用户协议
知识库、笔记、教程类应用
后端动态下发HTML内容的展示页面
技术文档、接口文档展示场景

八、开源共建

本项目基于 Apache-2.0 开源协议，免费开源、允许商用、无需授权。

目前持续迭代中，欢迎各位开发者：

🌟 GitHub 点 Star 支持作者更新迭代

🐛 发现 Bug、兼容问题可提 Issue

✨ 有新需求、功能优化欢迎提交 PR

项目官方地址

🌐 官网文档：https://www.htmlrichtext.com（最全API文档、更新日志、实战教程）

OHPM 仓库：https://ohpm.openharmony.cn/#/cn/detail/htmlrichtext

GitHub 仓库：https://github.com/oldwounds2120/html-rich-text