Flutter 鸿蒙化适配：Markdown 文档渲染与代码高亮实现

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
一、项目背景与目标
在开源鸿蒙（OpenHarmony）生态中，跨平台内容展示是开发者社区的核心需求之一。为了在 Flutter 应用中实现 Markdown 文档渲染、代码高亮与图片加载，我们对 flutter_markdown 与 flutter_highlight 三方库进行了鸿蒙化适配，完成了完整的基础校验与兼容性修复。
本次改造的核心目标：
实现 Markdown 基础文本、列表、链接渲染
支持代码块语法高亮，适配浅色 / 深色主题
兼容 OpenHarmony 权限体系下的网络图片加载
保证不同设备尺寸下的排版一致性
二、技术方案与依赖配置

1. 依赖选型
   核心渲染库：flutter_markdown（官方推荐的轻量级 Markdown 渲染方案）
   代码高亮：flutter_highlight + highlight.js 语法支持
   扩展预留：预留 markdown_widget 作为后续高自定义渲染方案的备选
2. pubspec.yaml 配置

name: oh_demo1
description: Flutter for OpenHarmony Markdown Render Demo
version: 1.0.0+1

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: sdk:flutter

dependencies:
  flutter:
    sdk:flutter
  flutter_markdown: ^0.6.18
  flutter_highlight: ^0.7.0
  highlight: ^0.7.0

dev_dependencies:
  flutter_test:
    sdk:flutter
  flutter_lints: ^2.0.0

三、核心代码实现

1. 错误边界与基础入口
   自定义错误边界组件，避免渲染异常导致的白屏问题，方便后续调试定位：

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_markdown/flutter_markdown.dart';
import 'package:flutter_highlight/flutter_highlight.dart';
import 'package:flutter_highlight/themes/github.dart';
import 'dart:ui' as ui; // 修复 PlatformDispatcher 编译错误

void main() {
  runApp(const _AppErrorBoundary(child: MyApp()));
}

// 自定义错误边界组件，替代 ErrorBoundary
class _AppErrorBoundary extends StatefulWidget {
  final Widget child;
  const _AppErrorBoundary({required this.child});

  @override
  State<_AppErrorBoundary> createState() => _AppErrorBoundaryState();
}

class _AppErrorBoundaryState extends State<_AppErrorBoundary> {
  Object? _error;
  StackTrace? _stackTrace;

  @override
  void initState() {
    super.initState();
    FlutterError.onError = (FlutterErrorDetails details) {
      setState(() {
        _error = details.exception;
        _stackTrace = details.stack;
      });
    };
  }

  @override
  Widget build(BuildContext context) {
    if (_error != null) {
      return MaterialApp(
        home: Scaffold(
          body: Center(
            child: SingleChildScrollView(
              padding: const EdgeInsets.all(16),
              child: Column(
                children: [
                  const Text("渲染出错啦", style: TextStyle(fontSize: 20, color: Colors.red)),
                  const SizedBox(height: 16),
                  Text("错误信息: $_error"),
                  const SizedBox(height: 8),
                  Text("堆栈: $_stackTrace"),
                ],
              ),
            ),
          ),
        ),
      );
    }
    return widget.child;
  }
}

2. Markdown 渲染与代码高亮实现

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter 鸿蒙 Markdown Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MarkdownDemoPage(),
    );
  }
}

class MarkdownDemoPage extends StatelessWidget {
  const MarkdownDemoPage({super.key});

  final String demoMarkdown = """
# Flutter 鸿蒙 Markdown 示例

## 基础文本渲染
这是一段 **加粗文本** 和 *斜体文本*，支持[开源鸿蒙社区](https://openharmonycrossplatform.csdn.net)链接跳转。

## 代码高亮示例
```dart
void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text("Markdown Demo")),
      ),
    );
  }
}

四、问题排查与后续优化

1. 本次编译问题修复
   PlatformDispatcher 报错：通过导入 dart:ui 并使用 ui.PlatformDispatcher 修复
   ErrorBoundary 不存在：替换为自定义的 _AppErrorBoundary 组件，避免渲染异常白屏
2. 后续优化方向
   接入 markdown_widget 实现更丰富的自定义渲染（如自定义代码块样式）
   支持本地 Markdown 文件加载与缓存
   优化大篇幅 Markdown 文档的渲染性能
   五、总结
   本次适配完成了 Flutter 应用在 OpenHarmony 生态下的 Markdown 文档渲染基础能力，解决了三方库兼容性、网络权限与异常白屏问题，为后续社区技术文档展示功能打下了基础。开发者可基于此方案快速实现跨平台技术博客、文档中心等场景的开发。