插件介绍

flutter_markdown 是一个用于渲染 Markdown 文本的 Flutter 包，它可以将简单的 Markdown 格式文本转换为富文本内容，包括文本样式、表格、链接等。这个包基于 Dart 的 markdown 包构建，专门为 Flutter 应用提供了 Markdown 渲染支持。

主要功能

• Markdown 语法支持：支持多种 Markdown 语法级别，包括基本语法、CommonMark、GitHub Flavored Markdown (GFM) 和 GitHub Web
• 丰富的文本格式：支持标题、列表、强调、链接、图片、代码块等多种 Markdown 元素
• 自定义样式：允许自定义 Markdown 渲染的样式，如字体大小、颜色、间距等
• Emoji 支持：支持直接插入 Emoji 或使用内联 Emoji 标签语法
• 图片支持：支持网络图片、本地文件图片和应用资源图片
• 选择性渲染：提供 Markdown、MarkdownBody 和 MarkdownRaw 等不同的渲染组件，适应不同的使用场景

语法支持级别

flutter_markdown 包支持四个级别的 Markdown 语法：

• 基本语法：遵循 John Gruber 原始的 Markdown 语法文档
• CommonMark：遵循 CommonMark 规范，澄清和规范了 Markdown 语法中的模糊或不明确之处
• GitHub Flavored (GFM)：GitHub 使用的 Markdown 方言，是 CommonMark 的严格超集，默认启用
• GitHub Web：在 GFM 基础上添加了标题 ID 和 Emoji 支持

鸿蒙平台支持

flutter_markdown 包完全支持鸿蒙平台，因为它是一个纯 Dart 实现的包，不依赖任何平台特定的 API。在鸿蒙应用开发过程中使用 flutter_markdown 可以帮助开发者轻松实现 Markdown 内容的渲染，适用于各种需要展示富文本内容的场景。

如何使用插件

包的引入

由于这是一个为鸿蒙平台定制修改的版本，需要以 git 形式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  flutter_markdown:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/flutter_markdown"

添加依赖后，运行 flutter pub get 命令来获取包：

flutter pub get

基本使用方法

使用 flutter_markdown 包非常简单，只需要将 Markdown 文本作为字符串传递给 Markdown 组件即可：

import 'package:flutter/material.dart';
import 'package:flutter_markdown/flutter_markdown.dart';

class MarkdownExample extends StatelessWidget {
  final String markdownSource = '''
# 标题一级
## 标题二级
### 标题三级

这是一个 **粗体** 文本和 *斜体* 文本的示例。

- 无序列表项 1
- 无序列表项 2
- 无序列表项 3

1. 有序列表项 1
2. 有序列表项 2
3. 有序列表项 3

[这是一个链接](https://example.com)

![这是一张图片](https://example.com/image.jpg)

```dart
// 这是一个代码块
void main() {
  print('Hello, World!');
}

‘’';

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text(‘Markdown 示例’)),
body: Markdown(data: markdownSource),
);
}
}

### 无滚动和无内边距版本

如果不需要默认的滚动行为和内边距，可以使用 `MarkdownBody` 组件：

```dart
MarkdownBody(data: markdownSource);

非 Material Design 环境使用

如果不想在 Material Design 环境外使用 Markdown，可以使用 MarkdownRaw 类：

MarkdownRaw(data: markdownSource);

API 调用与配置

1. 基本配置

Markdown(
  data: markdownSource,  // 要渲染的 Markdown 文本
  selectable: true,     // 是否允许文本选择
  controller: ScrollController(),  // 滚动控制器
  onTapLink: (String text, String? href, String title) {
    // 处理链接点击事件
    print('点击了链接: $href');
  },
  onImageTap: (String imageUrl, int? startOffset, int? endOffset) {
    // 处理图片点击事件
    print('点击了图片: $imageUrl');
  },
);

2. 自定义样式

可以使用 MarkdownStyleSheet 类自定义 Markdown 渲染的样式：

Markdown(
  data: markdownSource,
  styleSheet: MarkdownStyleSheet(
    // 标题样式
    h1: TextStyle(fontSize: 32, fontWeight: FontWeight.bold, color: Colors.blue),
    h2: TextStyle(fontSize: 28, fontWeight: FontWeight.bold),
    h3: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
    
    // 文本样式
    p: TextStyle(fontSize: 16, color: Colors.black87),
    
    // 强调样式
    strong: TextStyle(fontWeight: FontWeight.bold),
    em: TextStyle(fontStyle: italic),
    
    // 链接样式
    a: TextStyle(color: Colors.blue, decoration: TextDecoration.underline),
    
    // 代码样式
    code: TextStyle(fontFamily: 'Monospace', backgroundColor: Colors.grey[100]),
    codeblockDecoration: BoxDecoration(
      color: Colors.grey[100],
      borderRadius: BorderRadius.circular(4),
    ),
    
    // 列表样式
    listBullet: TextStyle(fontSize: 20),
    listNumber: TextStyle(fontSize: 16),
    
    // 引用样式
    blockquoteDecoration: BoxDecoration(
      border: Border(left: BorderSide(color: Colors.blue, width: 4)),
    ),
  ),
);

3. Emoji 支持

flutter_markdown 支持两种方式插入 Emoji：

直接插入 Emoji

Markdown(
  data: 'Insert emoji here😀 ',
  selectable: true,
);

使用内联 Emoji 标签

需要导入 markdown 包并添加 EmojiSyntax 扩展：

import 'package:markdown/markdown.dart' as md;

Markdown(
  data: 'Insert emoji :smiley: here',
  selectable: true,
  extensionSet: md.ExtensionSet(
    md.ExtensionSet.gitHubFlavored.blockSyntaxes,
    <md.InlineSyntax>[md.EmojiSyntax(), ...md.ExtensionSet.gitHubFlavored.inlineSyntaxes],
  ),
);

4. 图片支持

flutter_markdown 支持三种类型的图片：

网络图片

![网络图片](https://example.com/image.jpg)

本地文件图片

// 首先获取本地文件路径
String localImagePath = '/path/to/local/image.jpg';

Markdown(
  data: '![本地图片]($localImagePath)',
);

应用资源图片

使用 resource: 前缀引用应用资源图片：

Markdown(
  data: '![资源图片](resource:assets/image.png)',
);

5. 自定义扩展

可以添加自定义的 Markdown 语法扩展：

import 'package:markdown/markdown.dart' as md;

// 自定义内联语法
class CustomInlineSyntax extends md.InlineSyntax {
  CustomInlineSyntax() : super(r'@([a-zA-Z0-9_]+)');
  
  @override
  bool onMatch(md.InlineParser parser, Match match) {
    String username = match.group(1)!;
    parser.addNode(md.Element.text('span', '@$username'));
    return true;
  }
}

// 使用自定义扩展
Markdown(
  data: 'Hello @flutter_markdown!',
  extensionSet: md.ExtensionSet(
    md.ExtensionSet.gitHubFlavored.blockSyntaxes,
    <md.InlineSyntax>[CustomInlineSyntax(), ...md.ExtensionSet.gitHubFlavored.inlineSyntaxes],
  ),
  styleSheet: MarkdownStyleSheet(
    span: TextStyle(color: Colors.blue),
  ),
);

完整示例

1. 配置 pubspec.yaml

name: flutter_markdown_example
description: A Flutter application demonstrating the use of flutter_markdown on HarmonyOS
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter

  flutter_markdown:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/flutter_markdown"

  cupertino_icons: ^1.0.2

  markdown: ^7.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/image.png

2. 创建示例代码

import 'package:flutter/material.dart';
import 'package:flutter_markdown/flutter_markdown.dart';
import 'package:markdown/markdown.dart' as md;

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Markdown Example',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        useMaterial3: true,
      ),
      home: const MarkdownExample(),
    );
  }
}

class MarkdownExample extends StatelessWidget {
  const MarkdownExample({Key? key}) : super(key: key);

  final String markdownSource = '''
# Flutter Markdown 示例

## 基本文本格式

这是一个 **粗体** 文本和 *斜体* 文本的示例。

## 列表

### 无序列表
- 项目 1
- 项目 2
- 项目 3

### 有序列表
1. 第一项
2. 第二项
3. 第三项

## 链接和图片

[Flutter 官方网站](https://flutter.dev/)

![Flutter Logo](https://flutter.dev/assets/flutter-lockup-c13da9c9303e26b8d5fc208d2a1fa20c1ef47eb021ecadf27046dea04c0cebf6.png)

![本地资源图片](resource:assets/image.png)

## 代码块

```dart
void main() {
  runApp(const MyApp());
}

引用

这是一个引用示例。
Markdown 是一种轻量级标记语言。

表格

表头 1	表头 2
单元格 1	单元格 2
单元格 3	单元格 4

Emoji 支持

直接插入 Emoji: 😀🎉

使用 Emoji 标签: 😃🎉
‘’';

@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text(‘Flutter Markdown Example’),
),
body: Markdown(
data: markdownSource,
selectable: true,
extensionSet: md.ExtensionSet(
md.ExtensionSet.gitHubFlavored.blockSyntaxes,
<md.InlineSyntax>[md.EmojiSyntax(), …md.ExtensionSet.gitHubFlavored.inlineSyntaxes],
),
styleSheet: MarkdownStyleSheet(
h1: const TextStyle(fontSize: 32, fontWeight: FontWeight.bold, color: Colors.blue),
h2: const TextStyle(fontSize: 28, fontWeight: FontWeight.bold),
code: TextStyle(fontFamily: ‘Monospace’, backgroundColor: Colors.grey[100]),
codeblockDecoration: BoxDecoration(
color: Colors.grey[100],
borderRadius: BorderRadius.circular(8),
padding: const EdgeInsets.all(12),
),
blockquoteDecoration: BoxDecoration(
border: const Border(left: BorderSide(color: Colors.blue, width: 4)),
color: Colors.blue[50],
),
),
onTapLink: (String text, String? href, String title) {
print(‘点击了链接: $href’);
},
onImageTap: (String imageUrl, int? startOffset, int? endOffset) {
print(‘点击了图片: $imageUrl’);
},
),
);
}
}

## 注意事项

1. **HTML 支持**：`flutter_markdown` 不支持内联 HTML，这与 Web 浏览器中的 Markdown 渲染器不同。

2. **性能考虑**：
   - 对于大段的 Markdown 文本，建议使用懒加载或分页加载
   - 避免在滚动列表中频繁渲染复杂的 Markdown 内容
   - 使用 `MarkdownBody` 代替 `Markdown` 以避免不必要的滚动行为

3. **图片加载**：
   - 确保网络图片 URL 可访问
   - 本地图片路径需要正确获取
   - 资源图片需要在 `pubspec.yaml` 中正确配置

4. **自定义样式**：
   - 使用 `MarkdownStyleSheet` 时，建议继承当前主题样式，而不是完全重新定义
   - 注意不同平台和设备的文本缩放设置

5. **Emoji 兼容性**：
   - 确保设备支持显示特定的 Emoji 字符
   - 使用 Emoji 标签时需要导入 `markdown` 包并添加 `EmojiSyntax` 扩展

6. **鸿蒙平台特殊考虑**：
   - `flutter_markdown` 是纯 Dart 包，完全支持鸿蒙平台
   - 不需要额外的平台特定配置
   - 可以与鸿蒙应用开发流程无缝集成

## 总结

`flutter_markdown` 是一个功能强大的 Markdown 渲染包，它为 Flutter 应用提供了全面的 Markdown 支持。作为一个纯 Dart 实现的包，它完全支持鸿蒙平台，可以帮助开发者轻松实现 Markdown 内容的渲染。

在鸿蒙上使用 `flutter_markdown` 的主要优势：

1. **功能全面**：支持多种 Markdown 语法级别和丰富的文本格式
2. **易于使用**：提供简单易用的 API，只需几行代码即可实现 Markdown 渲染
3. **高度可定制**：允许自定义样式、添加扩展和处理各种事件
4. **跨平台兼容**：在鸿蒙平台上与其他平台表现一致，无需额外配置
5. **性能优良**：优化的渲染性能，适合各种规模的 Markdown 内容

`flutter_markdown` 适用于各种需要展示富文本内容的场景，如帮助文档、用户协议、内容展示等。通过灵活的配置和自定义选项，可以满足不同应用的需求，为用户提供良好的阅读体验。

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