鸿蒙应用怎么展示 Markdown？拆解 ArkTS 库 markdown4j

走进 hxa-atpc 开源三方库

做一个鸿蒙手机应用的帮助页：服务端下发 Markdown，正文里有标题、列表、链接和代码块。接下来，要把这段文本转换成什么，又交给谁来展示？

如果你的方案是“先转成 HTML，再由页面承载”，可以看看 hxa-atpc 的 markdown4j。这个库提供 Markdown 到 HTML 的转换能力，同时留出了语法扩展和输出定制接口。[1]

它适合承担内容转换这一环。页面样式、链接跳转和外部资源加载，还需要宿主应用配合。 先把这条链路分清楚，接入时就容易判断问题出在哪里。

一、从 Markdown 到手机页面，中间经过什么？

图：根据库的接口和 Demo 整理的流程示意，非真机运行截图。

例如，输入这段内容：

# 使用帮助

支持 **离线阅读**。

转换后，先检查是否生成了对应的 h1、p 和 strong 标签。接下来，宿主再把 HTML 片段放进展示页面，为标题、段落、图片等元素提供样式。

仓库里的手册 Demo 就把这两步分开处理：先调用转换接口，再补上 HTML 文档结构和 CSS，交给 Web 组件预览；同时提供 HTML 源码视图，方便对照结果。[2]

标题没转出来，先看转换输出；标签已经正确，字号、间距却不对，就继续检查页面样式和展示方式。

二、它能处理哪些内容？

仓库将这个项目描述为纯 ArkTS HAR，包名为 @hxa-atpc/markdown4j，适配版本为 1.0.2。库模块的依赖清单为空，没有额外 OHPM 三方依赖。[1][3]

能力可以分成三层理解。

第一层是基础 Markdown。 标题、段落、强调、列表、引用、链接、图片和代码等内容，构成常见帮助页与文章正文。仓库 Demo 提供了这些输入的示例。[1][2]

第二层是 Extended Profile。 手册 Demo 还列出了删除线、上标、围栏代码块等扩展写法。评估时，应把自己内容平台实际使用的语法拿来逐项对照。[2]

这里有一个容易误判的细节：公开接口里虽然导出了 TablePlugin，但 README 明确说明它是未完成的占位实现，源码也没有有效输出逻辑。不能因为看到了这个类名，就认定表格插件已经可用。 业务依赖表格时，应另行验证所需的具体语法和输出。[1][4]

第三层是输出定制。 ExtDecorator 可以给指定标签加类名或属性；CodeBlockEmitter 提供代码块输出方式；插件则可以扩展专用内容块。[1][4]

比如，给段落加上 md-paragraph 类名，宿主页面就能用对应 CSS 调整阅读样式。类名和样式需要两边配合；代码块生成标签后，也需要另外安排语法高亮能力。

三、先接通一个最小示例

对于普通业务接入，README 推荐使用已发布的 HAR。按仓库给出的方式，在工程根目录和 entry 模块各自的 oh-package.json5 中，合并以下依赖，保留原有配置：[1]

{
  "dependencies": {
    "@hxa-atpc/markdown4j": "1.0.2"
  }
}

然后分别在工程根目录、entry 目录执行：

ohpm install

依赖安装完成后，可以先做一个显示 HTML 源码的页面。将已有 ArkUI 工程的 entry/src/main/ets/pages/Index.ets 替换为下面的示例，点击按钮观察输出：

import { Markdown4jProcessor } from '@hxa-atpc/markdown4j';

@Entry
@Component
struct Index {
  @State html: string = '';

  build() {
    Column({ space: 16 }) {
      Button('转换 Markdown')
        .onClick(() => {
          const processor = new Markdown4jProcessor();
          this.html = processor.process(
            '# 使用帮助\n\n支持 **离线阅读**。'
          );
        })

      Text(this.html)
        .width('100%')
    }
    .width('100%')
    .padding(24)
  }
}

这里的 Text 用来查看生成的标签字符串。按 README 的基础示例，应检查输出是否包含这样的结构：[1]

<h1>使用帮助</h1>
<p>支持 <strong>离线阅读</strong>。</p>

代码按公开导出和源码整理，输出结构为对照目标；本文未编译该示例，也未进行模拟器或真机验证。

先确认转换结果，再接页面预览，可以把依赖、解析和排版问题分步排查。完整的预览参考见手册 Demo 中的 PlaygroundPage.ets。[2]

如果需要修改库源码，再考虑本地模块接入。README 提醒，这时除了修改依赖文件，还要在工程根 build-profile.json5 的 modules 中登记源码模块路径。[1]

四、安全模式要显式选择

Markdown4jProcessor 的默认门面没有开启 HTML 安全模式。 源码中的配置构建器默认 safeMode = false，门面的初始化过程也没有调用 enableSafeMode()。[4]

需要显式配置时，可以使用引擎入口：

import {
  Processor,
  Configuration,
  ExtDecorator
} from '@hxa-atpc/markdown4j';

const decorator = new ExtDecorator()
  .addStyleClass('md-paragraph', ['p']);

const config = Configuration.builder()
  .enableSafeMode()
  .setDecorator(decorator)
  .build();

const html: string = Processor.process(
  '# 使用帮助\n\n支持 **离线阅读**。',
  config
);

这个示例显式开启了文档所称的“HTML 安全模式”，并给段落设置类名；它没有注册插件，也没有完整复制默认门面的其他配置。两种入口的行为应分别核对。[1][4]

能确认的是：库提供这个配置项及相应调用方式。来自用户、外部文件或远程服务的内容是否满足业务要求，需要结合实际输入和最终展示环境验证。开启开关本身，不能作为所有输入都已安全处理的验收结论。

接入时，至少把普通 Markdown、内嵌 HTML、不同链接和图片地址分别送入转换流程，对照输出，再检查页面如何处理这些内容。

五、插件扩展，还会改变哪些条件？

默认门面注册了 yuml、sequence、include 三个插件，使用条件各有不同：[1][4]

插件	当前用途	接入时关注什么
yuml	拼出外部图表地址的 img 标签	转换阶段只拼字符串，图片显示仍涉及外部资源加载
sequence	请求外部时序图服务，再嵌入图片	使用异步入口，处理服务可达性和失败情况
include	把指定沙箱文件或 HTTP(S) 地址的内容加入输出	约束文件及地址来源，区分本地读取与网络请求

对于需要异步处理的内容，可以使用 processAsync()。例如 sequence 走同步入口时，会输出需要异步处理的占位注释。[4]

include 还有一个细节：当前源码的同步实现也会尝试读取本地文件；远程地址则需要异步处理。因此，不能笼统理解为“使用同步入口就完全不会读取文件”。[4]

README 的权限栏声明了 ohos.permission.INTERNET。[1][4][5]

对宿主而言，纯文本转换、读取本地文件、请求外部服务，应按实际启用的路径分别检查权限和运行条件。需要离线帮助页时，先确认内容是否真的依赖这些扩展。

六、接入前，把这四件事对齐

版本和工程条件。 本文核对的仓库适配版本为 1.0.2，上游版本为 2.2，许可证为 Apache-2.0。README 和手册 Demo 标注的兼容 SDK 为 5.1.1(19)，目标 SDK 为 6.0.2(22)；接入前，应对照自己工程的 SDK 配置确认。[1][3][5]

内容语法。 拿一篇真实帮助文档做样本，检查标题、嵌套列表、代码块、链接、图片，以及项目依赖的扩展语法。最简单的标题转换成功，还不足以判断整套内容都能迁移。

输入来源。 自有文案、用户编辑和外部导入内容，各自需要怎样的配置、插件与输出检查，应在业务里明确。

展示效果。 HTML 源码检查通过后，再看手机页面：长代码是否溢出、图片是否适配宽度、链接怎样跳转、深浅色主题是否清晰。

如果你正在做帮助文档、公告正文或文章预览，而且已经选择 HTML 作为展示链路，markdown4j 值得进入接入验证。需要完整编辑器、原生富文本页面或复杂笔记产品时，还要继续组合相应的编辑与展示能力。

你在鸿蒙应用里展示 Markdown，最难处理的是代码块、表格，还是带图片和链接的正文？欢迎留言说说具体场景。

---

依据：

1. GitCode 项目及 README：功能说明、接入方式、兼容性与许可证。
2. 手册 Demo 的转换与预览页面：语法样例、HTML 包装与 Web 预览。
3. 库模块包配置：包名、版本、依赖和许可证声明。
4. 库源码目录：Markdown4jProcessor、Configuration、装饰器及各插件实现。
5. 手册 Demo 工程：build-profile.json5 的 SDK 配置、entry/src/main/module.json5 的网络权限声明。