欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
前言
Markdown 因其简洁的语法，已成为开发者编写文档、博客、评论的首选格式。
在 Flutter 应用中，我们经常需要渲染 Markdown 内容（如帮助文档、Terms of Service、用户评论）。
markdown 是 Dart 官方维护的标准库，它负责将 Markdown 文本解析为抽象语法树（AST）或直接转换为 HTML。它是 flutter_markdown 等高层 UI 库的基石。
对于 OpenHarmony 开发者，如果你需要自己实现一个轻量级的 Markdown 渲染器，或者需要对 Markdown 文本进行预处理（如提取目录、过滤敏感词），直接使用 markdown 库是最高效的选择。
一、核心原理
markdown 库的工作流程：
Block Parser
Inline Parser
HtmlRenderer
CustomRenderer
Markdown 文本
块级节点 (List)
抽象语法树 (Nodes)
HTML 字符串
Flutter Widget / 鸿蒙 UI
二、OpenHarmony 适配说明
markdown 是 Pure Dart 库，无平台依赖，100% 兼容 OpenHarmony 。
它的纯文本处理特性意味着它不需要任何原生的 WebView 或渲染引擎支持，非常适合鸿蒙早期的原生应用开发。
三、基础用例
3.1 基础转换 (Markdown -> HTML)
dart
import 'package:markdown/markdown.dart';
void main() {
String md = '''
# Hello OpenHarmony
This is a **bold** text.
- Item 1
- Item 2
''';
// 默认转换为 HTML
String html = markdownToHtml(md);
print(html);
// 输出:
// <h1>Hello OpenHarmony</h1>
// <p>This is a <strong>bold</strong> text.</p>
// <ul><li>Item 1</li><li>Item 2</li></ul>
}
3.2 使用扩展语法 (GitHub Flavored)
默认解析器只支持标准 Markdown。如果需要支持表格、删除线等 GitHub 风格语法，需要启用扩展。
dart
String mdTable = '''
| 库名 | 适配状态 |
| -- | -- |
| markdown | ✅ |
''';
String html = markdownToHtml(
mdTable,
extensionSet: ExtensionSet.gitHubFlavored,
);3.3 自定义语法拓展 (主要用例)
假设你想支持一种自定义语法，比如 @[username] 自动转换为用户链接。
dart
class MentionSyntax extends InlineSyntax {
// 匹配 @[xxx]
MentionSyntax() : super(r'@\[(.*?)\]');
@override
bool onMatch(InlineParser parser, Match match) {
// 创建一个 Element 节点
final anchor = Element.text('a', match[1]!);
anchor.attributes['href'] = '/user/${match[1]}';
anchor.attributes['class'] = 'user-mention';
parser.addNode(anchor);
return true;
}
}
void customSyntax() {
var md = 'Hello @[张三], welcome!';
var html = markdownToHtml(
md,
inlineSyntaxes: [MentionSyntax()]
);
print(html);
// <p>Hello <a href="/user/WangBaolong" class="user-mention">WangBaolong</a>, welcome!</p>
}
四、完整实战示例：鸿蒙文档提取器
这个示例不生成 HTML，而是演示如何遍历 Markdown 的 AST（抽象语法树），从中提取所有的"标题"生成目录（TOC），并提取所有的"图片链接"进行预加载。这是开发博客 App 或文档阅读器时的常见需求。
dart
import 'package:markdown/markdown.dart';
/// 一个简单的 AST 访问者，用于提取信息
class DocumentAnalyzer implements NodeVisitor {
final List<String> toc = []; // 目录
final List<String> images = []; // 图片链接
@override
bool visitElementBefore(Element element) {
// 提取 H1-H6 标题
if (RegExp(r'h[1-6]').hasMatch(element.tag)) {
final text = element.textContent;
toc.add('${element.tag}: $text');
}
// 提取图片
if (element.tag == 'img') {
final src = element.attributes['src'];
if (src != null) images.add(src);
}
return true; // 继续深入子节点
}
@override
void visitText(Text text) {
// 不需要处理纯文本
}
@override
void visitElementAfter(Element element) {
// 节点结束时
}
}
void main() {
final markdownSource = '''
# 鸿蒙开发指南
## 1. 环境搭建
安装 DevEco Studio...
## 2. 编写第一个 App
Hello World...
### 2.1 UI 布局
使用 Column 和 Row...
''';
// 1. 解析为 AST 节点列表
final document = Document();
final List<Node> nodes = document.parseLines(markdownSource.split('\n'));
// 2. 遍历 AST
final analyzer = DocumentAnalyzer();
for (var node in nodes) {
node.accept(analyzer);
}
// 3. 输出结果
print('=== 📋 目录 (TOC) ===');
analyzer.toc.forEach(print);
print('\n=== 🖼️ 资源列表 (需预加载) ===');
analyzer.images.forEach(print);
// 实际应用中，你可以将 images 列表传给 CachedNetworkImage 进行预缓存
}
五、总结
markdown 库虽不直接提供 UI Widget，但它提供了最底层的解析能力。
在 OpenHarmony 开发中，利用好它的 AST 能力，你可以实现：
- 高度定制的富文本渲染 ：将 AST 映射为鸿蒙原生的
RichText或 Flutter Widget。 - 文档分析工具：自动生成大纲、统计字数、检查坏链。
它是构建内容型 App 不可或缺的基础设施。