Flutter for OpenHarmony：markdown 纯 Dart 解析引擎（将文本转化为结构化 HTML/UI） 深度解析与鸿蒙适配指南

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.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)

import'package:markdown/markdown.dart';voidmain(){String md =''' # Hello OpenHarmony This is a **bold** text. - Item 1 - Item 2 ''';// 默认转换为 HTMLString 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 风格语法，需要启用扩展。

String mdTable =''' | 库名 | 适配状态 | | -- | -- | | markdown | ✅ | ''';String html =markdownToHtml( mdTable, extensionSet:ExtensionSet.gitHubFlavored,);

3.3 自定义语法拓展 (主要用例)

假设你想支持一种自定义语法，比如 @[username] 自动转换为用户链接。

classMentionSyntaxextendsInlineSyntax{// 匹配 @[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);returntrue;}}voidcustomSyntax(){var md ='Hello @[张三], welcome!';var html =markdownToHtml( md, inlineSyntaxes:[MentionSyntax()]);print(html);// <p>Hello <a href="/user/WangBaolong">WangBaolong</a>, welcome!</p>}

四、完整实战示例：鸿蒙文档提取器

这个示例不生成 HTML，而是演示如何遍历 Markdown 的 AST（抽象语法树），从中提取所有的“标题”生成目录（TOC），并提取所有的“图片链接”进行预加载。这是开发博客 App 或文档阅读器时的常见需求。

import'package:markdown/markdown.dart';/// 一个简单的 AST 访问者，用于提取信息classDocumentAnalyzerimplementsNodeVisitor{finalList<String> toc =[];// 目录finalList<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);}returntrue;// 继续深入子节点}@overridevoidvisitText(Text text){// 不需要处理纯文本}@overridevoidvisitElementAfter(Element element){// 节点结束时}}voidmain(){final markdownSource =''' # 鸿蒙开发指南 ## 1. 环境搭建 ![安装截图](https://example.com/install.png) 安装 DevEco Studio... ## 2. 编写第一个 App ![运行效果](https://example.com/demo.gif) Hello World... ### 2.1 UI 布局 使用 Column 和 Row... ''';// 1. 解析为 AST 节点列表final document =Document();finalList<Node> nodes = document.parseLines(markdownSource.split('\n'));// 2. 遍历 ASTfinal 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 能力，你可以实现：

1. 高度定制的富文本渲染：将 AST 映射为鸿蒙原生的 RichText 或 Flutter Widget。
2. 文档分析工具：自动生成大纲、统计字数、检查坏链。

它是构建内容型 App 不可或缺的基础设施。