欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

Markdown 因其简洁的语法，已成为开发者编写文档、博客、评论的首选格式。
在 Flutter 应用中，我们经常需要渲染 Markdown 内容（如帮助文档、Terms of Service、用户评论）。

markdown 是 Dart 官方维护的标准库，它负责将 Markdown 文本解析为抽象语法树（AST）或直接转换为 HTML。它是 flutter_markdown 等高层 UI 库的基石。

对于 OpenHarmony 开发者，如果你需要自己实现一个轻量级的 Markdown 渲染器，或者需要对 Markdown 文本进行预处理（如提取目录、过滤敏感词），直接使用 markdown 库是最高效的选择。

一、核心原理

markdown 库的工作流程：

二、OpenHarmony 适配说明

markdown 是 Pure Dart 库，无平台依赖，100% 兼容 OpenHarmony。
它的纯文本处理特性意味着它不需要任何原生的 WebView 或渲染引擎支持，非常适合鸿蒙早期的原生应用开发。

三、基础用例

3.1 基础转换 (Markdown -> HTML)

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 风格语法，需要启用扩展。

String mdTable = '''
| 库名 | 适配状态 |
| -- | -- |
| markdown | ✅ |
''';

String html = markdownToHtml(
  mdTable, 
  extensionSet: ExtensionSet.gitHubFlavored,
);

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

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

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 或文档阅读器时的常见需求。

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. 环境搭建
![安装截图](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();
  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 能力，你可以实现：

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

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