Markdown 转 HTML 转换库

markdown4j 鸿蒙 ArkTS 库

本项目基于 markdown4j 开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

1. 项目介绍

本库将 markdown4j 的 Markdown 转 HTML 能力迁移为 HarmonyOS 原生 ArkTS HAR，包名 @hxa-atpc/markdown4j，版本 1.0.2。纯 ArkTS 实现，无三方 ohpm 依赖。支持标准语法、Extended Profile 扩展语法、HTML 安全模式、插件与装饰器扩展点。

源码在 ohos_library/。ohos-hardemo 是手册 Demo，ohos-hardemo-auto 是黑盒用例 Demo。公开导出见 ohos_library/Index.ets。

2. 集成指南

下载

从 GitCode 克隆本仓库：

git clone https://gitcode.com/hxa-atpc/markdown4j.git

安装并编译 Demo

在 ohos-hardemo/ 目录执行：

cd ohos-hardemo
ohpm install
hvigorw -e assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

HAP 产物：ohos-hardemo/entry/build/default/outputs/default/entry-default-unsigned.hap。

集成到你的工程

对外集成请使用 方式一（ohpm 依赖已发布的 HAR）。方式二供克隆本仓库后修改 ohos_library 源码、本地联调使用。包名均为 @hxa-atpc/markdown4j。

方式一：HAR 包依赖

工程根 oh-package.json5（保留已有 modelVersion 等字段，补充 dependencies）：

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

entry/oh-package.json5：

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

然后在工程根与 entry/ 分别执行：

ohpm install

方式二：源码依赖（开发 / 改库）

把宿主工程与本仓库的 ohos_library 放在相邻目录（或按实际相对路径改）。

常见目录关系（file: 路径均相对宿主工程根目录）：

场景	宿主工程位置	`ohos_library` 位置	工程根依赖示例
克隆全仓，宿主在仓库内	`markdown4j/MyApp/`	`markdown4j/ohos_library/`	`file:../ohos_library`
只拷贝 HAR 目录	`MyApp/`	与 `MyApp/` 同级 `ohos_library/`	`file:../ohos_library`
宿主在仓外	`workspace/MyApp/`	`workspace/markdown4j/ohos_library/`	`file:../markdown4j/ohos_library`

只改 oh-package.json5 不够，还必须改工程根 build-profile.json5：在 modules 里、entry 模块之后增加本库源码模块（name 以 ohos_library/src/main/module.json5 的 module.name 为准，常见为 library；srcPath 按上表相对路径填写），例如：

{
  "name": "library",
  "srcPath": "../ohos_library"
}

工程根 oh-package.json5（保留已有 modelVersion 等字段，补充 dependencies）：

{
  "modelVersion": "6.0.2",
  "dependencies": {
    "@hxa-atpc/markdown4j": "file:../ohos_library"
  }
}

entry/oh-package.json5（相对 ohos_library 通常多一层 ../）：

{
  "dependencies": {
    "@hxa-atpc/markdown4j": "file:../../ohos_library"
  }
}

工程根 build-profile.json5（在已有 app 段上补充 modules；compatibleSdkVersion 与 useNormalizedOHMUrl 不可省略）：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.1.1(19)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ]
    },
    {
      "name": "library",
      "srcPath": "../ohos_library"
    }
  ]
}

然后在工程根与 entry/ 分别执行：

ohpm install

导入包名：@hxa-atpc/markdown4j。

3. 使用说明

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

const processor = new Markdown4jProcessor();
const html: string = processor.process('# 标题\n\n**粗体** 与 *斜体*');
// html === '<h1>标题</h1>\n<p><strong>粗体</strong> 与 <em>斜体</em></p>\n'

自定义配置与异步插件：

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

const decorator = new ExtDecorator()
  .addStyleClass('md-para', ['p'])
  .addHtmlAttribute('data-app', 'demo', ['p', 'ul'])
  .useCompactStyle();

const config = Configuration.builder()
  .enableSafeMode()
  .convertNewline2Br()
  .setCodeBlockEmitter(new CodeBlockEmitter())
  .setDecorator(decorator)
  .build();

const safeHtml = Processor.process('内容\n含 <script> 的文本', config);

const facade = new Markdown4jProcessor();
const fileHtml = facade.processFile(context.filesDir + '/doc.md');
const seqHtml = await facade.processAsync('%%%sequence style=default\nalice->bob: hi\n%%%\n');

Markdown4jProcessor 默认启用 Extended Profile、ExtDecorator、换行转 <br/>，并注册 yuml / sequence / include 插件。手册 Demo 见 ohos-hardemo，黑盒 Demo 见 ohos-hardemo-auto。

运行 Demo

cd ohos-hardemo
ohpm install
hvigorw -e assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

HAP 产物：ohos-hardemo/entry/build/default/outputs/default/entry-default-unsigned.hap。

4. 接口文档

下列均为 Index.ets 公开导出。签名以源码为准。

门面

接口	说明
`Markdown4jProcessor`	默认配置门面。`process` / `processAsync` / `processFile` / `processFileAsync` / `registerPlugins` / `setDecorator` / `addHtmlAttribute` / `addStyleClass`

引擎

接口	说明
`Processor`	引擎入口。静态方法 `process` / `processSafe` / `processWithDecorator` / `processWithDecoratorSafe` / `processAsync`
`Configuration`	`DEFAULT` / `DEFAULT_SAFE` / `defaultConfig()` / `defaultSafeConfig()` / `builder()`
`ConfigurationBuilder`	`enableSafeMode` / `forceExtentedProfile` / `convertNewline2Br` / `setSafeMode` / `setEncoding` / `setDecorator` / `setCodeBlockEmitter` / `setSpecialLinkEmitter` / `registerPlugins` / `build`

装饰器

接口	说明
`Decorator`	26 组 `openXxx` / `closeXxx` 标签输出接口（Paragraph、Blockquote、CodeBlock、CodeSpan、Headline、Strong、Strike、Emphasis、Super、OrderedList、UnorderedList、ListItem、horizontalRuler、Link、Image 等）
`DefaultDecorator`	标准 HTML 标签输出
`ExtDecorator`	`addHtmlAttribute(name, value, tags)` / `addStyleClass(styleClass, tags)` / `useCompactStyle()`
`BlockEmitter`	围栏/缩进代码块自定义输出
`SpanEmitter`	`[[特殊链接]]` 自定义输出
`CodeBlockEmitter`	输出 `<pre><code class="meta">`
`HtmlAttributes`	按标签累积 HTML 属性

插件

围栏语法为至少三个 %：%%%插件id 参数。

接口	说明
`Plugin`	同步插件基类，`emit(out, lines, params)`
`AsyncPlugin`	异步插件基类，`emitAsync`；同步路径输出占位注释
`YumlPlugin`	id=`yuml`，拼接 yuml.me 图表 URL 的 `<img>`，同步
`WebSequencePlugin`	id=`sequence`，POST websequencediagrams.com 并嵌入 PNG，异步
`IncludePlugin`	id=`include`，嵌入沙箱文件或 `http(s)` URL 内容，异步
`TablePlugin`	id=`table`，上游未完成的占位实现（无输出）

底层类型

接口	说明
`Emitter`	HTML 发射器
`LinkRef`	链接引用
`Block`	行/块链表结构
`Line`	行状态与行类型判定
`Utils`	转义与扫描工具
`HTML`	实体/元素静态表
`HTMLElement`	HTML 元素枚举
`MarkToken`	行内 token 枚举
`LineType`	行类型枚举
`BlockType`	块类型枚举

5. 约束与限制

兼容性

项	版本
上游 Atpc SDK	markdown4j `2.2`（`org.commonjava.googlecode.markdown4j:markdown4j`）
鸿蒙适配版本	`1.0.2`
版本号对照	`2.2-ohos-1.0.2`
鸿蒙 SDK	`compatibleSdkVersion` / `targetSdkVersion`：`5.1.1(19) / 6.0.2(22)`

权限

无。本库不申请、不依赖任何系统权限。

6. 开源license

7. 问题反馈渠道

使用过程中如有问题，欢迎在仓库提交 Issue，我们会及时跟进：

GitCode Issue：https://gitcode.com/hxa-atpc/markdown4j/issues
也欢迎提交 Pull Request 共建：https://gitcode.com/hxa-atpc/markdown4j/pulls

提交 Issue 时请尽量附上 HarmonyOS SDK 版本、复现步骤与 hilog 日志。

ohpm install @hxa-atpc/markdown4j

Introduction