鸿蒙flutter三方库适配——笔记与知识管理应用：Flutter Markdown实战

本文介绍了一个基于Flutter和flutter_markdown库开发的跨平台笔记与知识管理应用。该应用采用MVC架构，核心功能包括Markdown编辑与实时预览、笔记管理（创建/编辑/删除）、标签分类和搜索过滤。通过Note数据模型实现结构化存储，使用Navigator进行页面跳转，并提供了完整的用户交互流程（如删除确认对话框）。该方案充分发挥了Flutter的跨平台优势，适配鸿蒙系统，为高效

2301_82270320

76人浏览 · 2026-04-11 13:00:19

2301_82270320 · 2026-04-11 13:00:19 发布

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

适配三方库地址：
https://gitcode.com/openharmony-tpc/flutter_packages/tree/master/packages/flutter_markdown

实战效果

在这里插入图片描述

1. 引言

在信息爆炸的时代，有效的知识管理变得越来越重要。无论是学生、教师、工程师还是创意工作者，都需要一个高效的工具来记录、组织和检索知识。Markdown作为一种轻量级标记语言，因其简洁、易读、易写的特点，成为了知识管理的理想选择。

本文将详细介绍如何使用Flutter和flutter_markdown库构建一个功能丰富的笔记与知识管理应用，实现Markdown编辑、实时预览、标签管理、搜索过滤等功能，为用户提供一个高效、美观的知识管理解决方案。

2. 技术栈选择

2.1 Flutter框架

Flutter是Google推出的跨平台UI框架，具有以下优势：

跨平台：一次编写，多平台运行（Android、iOS、Web、鸿蒙等）
高性能：使用Dart语言和Skia渲染引擎，性能接近原生应用
热重载：开发过程中可以实时查看代码变更效果
丰富的UI组件：提供了大量内置的Material Design和Cupertino风格的组件
活跃的社区：拥有庞大的开发者社区和丰富的第三方库

2.2 flutter_markdown库

flutter_markdown是Flutter官方维护的Markdown渲染库，具有以下特点：

完整的Markdown语法支持：支持标题、列表、链接、代码块、引用、表格等Markdown元素
自定义样式：可以通过MarkdownStyleSheet自定义Markdown元素的样式
可交互性：支持链接点击、代码块复制等交互功能
性能优化：采用惰性渲染，提高大型Markdown文档的渲染性能
鸿蒙平台适配：已适配鸿蒙平台，确保在鸿蒙设备上的正常运行

2.3 其他依赖库

shared_preferences：用于本地存储笔记数据
path_provider：用于获取文件系统路径
intl：用于日期格式化
provider：用于状态管理

3. 应用架构设计

3.1 整体架构

我们的笔记与知识管理应用采用MVC（Model-View-Controller）架构：

Model：负责数据模型的定义和数据存储
View：负责UI界面的渲染
Controller：负责业务逻辑的处理

3.2 核心数据模型

class Note {
  final String id;
  final String title;
  final String content;
  final List<String> tags;
  final DateTime createdAt;
  final DateTime updatedAt;

  Note({
    required this.id,
    required this.title,
    required this.content,
    this.tags = const [],
    required this.createdAt,
    required this.updatedAt,
  });

  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'title': title,
      'content': content,
      'tags': tags.join(','),
      'createdAt': createdAt.toIso8601String(),
      'updatedAt': updatedAt.toIso8601String(),
    };
  }

  factory Note.fromMap(Map<String, dynamic> map) {
    return Note(
      id: map['id'],
      title: map['title'],
      content: map['content'],
      tags: map['tags'].toString().split(','),
      createdAt: DateTime.parse(map['createdAt']),
      updatedAt: DateTime.parse(map['updatedAt']),
    );
  }
}

核心技术点分析：

数据结构：Note类包含id、标题、内容、标签、创建时间和更新时间等属性，完整地描述了一篇笔记的所有信息。
序列化与反序列化：提供了toMap()和fromMap()方法，用于笔记数据的序列化和反序列化，方便存储和读取。
标签管理：使用List<String>类型存储标签，支持为笔记添加多个标签，方便分类管理。

3.3 页面结构

应用包含两个主要页面：

笔记列表页面：显示所有笔记的概览，包括标题、摘要、标签和更新时间，支持搜索和标签过滤。
笔记编辑页面：用于创建和编辑笔记，包含标题编辑、标签管理、Markdown编辑和预览功能。

4. 核心功能实现

4.1 笔记管理

4.1.1 笔记的创建

void _addNote() {
  final newNote = Note(
    id: DateTime.now().millisecondsSinceEpoch.toString(),
    title: '新笔记',
    content: '# 新笔记\n\n开始编写你的笔记...',
    tags: [],
    createdAt: DateTime.now(),
    updatedAt: DateTime.now(),
  );
  Navigator.push(
    context,
    MaterialPageRoute(
      builder: (context) => NoteEditor(note: newNote, onSave: (updatedNote) {
        setState(() {
          _notes.add(updatedNote);
          _saveNotes();
        });
      }),
    ),
  );
}

核心技术点分析：

唯一ID生成：使用DateTime.now().millisecondsSinceEpoch.toString()生成唯一的笔记ID，确保每条笔记都有一个唯一标识。
导航：使用Navigator.push导航到笔记编辑页面，传入新创建的笔记对象。
回调函数：通过onSave回调函数，在笔记保存后更新笔记列表。

4.1.2 笔记的编辑

void _editNote(Note note) {
  Navigator.push(
    context,
    MaterialPageRoute(
      builder: (context) => NoteEditor(note: note, onSave: (updatedNote) {
        setState(() {
          final index = _notes.indexWhere((n) => n.id == updatedNote.id);
          if (index != -1) {
            _notes[index] = updatedNote;
            _saveNotes();
          }
        });
      }),
    ),
  );
}

核心技术点分析：

笔记定位：使用indexWhere方法根据笔记ID找到要更新的笔记在列表中的位置。
状态更新：更新找到的笔记对象，并调用_saveNotes()方法保存到本地存储。

4.1.3 笔记的删除

void _deleteNote(Note note) {
  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: const Text('删除笔记'),
      content: const Text('确定要删除这篇笔记吗？'),
      actions: [
        TextButton(
          onPressed: () => Navigator.pop(context),
          child: const Text('取消'),
        ),
        TextButton(
          onPressed: () {
            setState(() {
              _notes.remove(note);
              _saveNotes();
            });
            Navigator.pop(context);
          },
          child: const Text('删除'),
        ),
      ],
    ),
  );
}

核心技术点分析：

用户确认：使用showDialog显示确认对话框，防止用户误操作。
状态更新：从笔记列表中移除要删除的笔记，并调用_saveNotes()方法保存到本地存储。

4.2 数据存储

4.2.1 保存笔记

Future<void> _saveNotes() async {
  final prefs = await SharedPreferences.getInstance();
  final noteIds = _notes.map((note) => note.id).toList();
  await prefs.setStringList('notes', noteIds);
  for (var note in _notes) {
    final noteMap = note.toMap();
    final noteString = noteMap.entries
        .map((entry) => '${entry.key}:${entry.value}')
        .join(';');
    await prefs.setString('note_${note.id}', noteString);
  }
  _extractTags();
}

核心技术点分析：

存储结构：使用shared_preferences存储笔记数据，采用键值对的形式，其中：
- notes键存储所有笔记的ID列表
- 每个笔记使用note_${id}作为键，存储序列化后的笔记数据
数据序列化：将笔记对象转换为字符串格式存储，使用分号分隔不同的属性。
标签提取：保存笔记后调用_extractTags()方法提取所有标签，用于标签过滤功能。

4.2.2 加载笔记

Future<void> _loadNotes() async {
  final prefs = await SharedPreferences.getInstance();
  final notesJson = prefs.getStringList('notes') ?? [];
  final List<Note> loadedNotes = [];
  for (var json in notesJson) {
    final noteString = await prefs.getString('note_$json');
    if (noteString != null) {
      final noteMap = noteString.split(';').asMap().map(
            (key, value) => MapEntry(value.split(':')[0], value.split(':')[1]),
          );
      loadedNotes.add(Note.fromMap(Map<String, dynamic>.from(noteMap)));
    }
  }
  setState(() {
    _notes = loadedNotes;
    _extractTags();
  });
}

核心技术点分析：

数据反序列化：从shared_preferences中读取笔记数据，将字符串格式转换回笔记对象。
错误处理：使用if (noteString != null)检查笔记数据是否存在，防止空指针异常。
状态更新：将加载的笔记列表更新到应用状态中，并调用_extractTags()方法提取所有标签。

4.3 Markdown编辑与预览

4.3.1 编辑器实现

class NoteEditor extends StatefulWidget {
  final Note note;
  final Function(Note) onSave;

  const NoteEditor({super.key, required this.note, required this.onSave});

  @override
  State<NoteEditor> createState() => _NoteEditorState();
}

class _NoteEditorState extends State<NoteEditor> {
  late TextEditingController _titleController;
  late TextEditingController _contentController;
  late List<String> _tags;
  bool _isPreviewMode = false;

  @override
  void initState() {
    super.initState();
    _titleController = TextEditingController(text: widget.note.title);
    _contentController = TextEditingController(text: widget.note.content);
    _tags = List.from(widget.note.tags);
  }

  @override
  void dispose() {
    _titleController.dispose();
    _contentController.dispose();
    super.dispose();
  }

  void _saveNote() {
    final updatedNote = Note(
      id: widget.note.id,
      title: _titleController.text,
      content: _contentController.text,
      tags: _tags,
      createdAt: widget.note.createdAt,
      updatedAt: DateTime.now(),
    );
    widget.onSave(updatedNote);
    Navigator.pop(context);
  }

  // 其他方法...
}

核心技术点分析：

状态管理：使用TextEditingController管理标题和内容的输入状态。
生命周期管理：在initState中初始化控制器和状态，在dispose中释放资源。
笔记更新：在_saveNote方法中创建更新后的笔记对象，调用回调函数保存并返回上一页。

4.3.2 实时预览

// 编辑和预览切换
Row(
  children: [
    Expanded(
      child: ElevatedButton(
        onPressed: () => setState(() => _isPreviewMode = false),
        style: ElevatedButton.styleFrom(
          backgroundColor: !_isPreviewMode ? Colors.deepPurple : null,
        ),
        child: const Text('编辑'),
      ),
    ),
    Expanded(
      child: ElevatedButton(
        onPressed: () => setState(() => _isPreviewMode = true),
        style: ElevatedButton.styleFrom(
          backgroundColor: _isPreviewMode ? Colors.deepPurple : null,
        ),
        child: const Text('预览'),
      ),
    ),
  ],
),
// 内容区域
Expanded(
  child: _isPreviewMode
      ? Padding(
          padding: const EdgeInsets.all(16.0),
          child: Container(
            decoration: BoxDecoration(
              border: Border.all(color: Colors.grey),
              borderRadius: BorderRadius.circular(8),
            ),
            padding: const EdgeInsets.all(16.0),
            child: Markdown(
              data: _contentController.text,
              styleSheet: MarkdownStyleSheet.fromTheme(Theme.of(context)),
            ),
          ),
        )
      : Padding(
          padding: const EdgeInsets.all(16.0),
          child: TextField(
            controller: _contentController,
            maxLines: null,
            decoration: const InputDecoration(
              hintText: '请输入 Markdown 文本...',
              border: OutlineInputBorder(),
            ),
            style: const TextStyle(fontSize: 16),
          ),
        ),
),

核心技术点分析：

模式切换：使用_isPreviewMode变量控制编辑模式和预览模式的切换。
Markdown渲染：使用MarkdownWidget渲染Markdown内容，支持实时预览。
样式适配：使用MarkdownStyleSheet.fromTheme从当前主题创建样式表，确保预览效果与应用主题一致。

4.4 工具栏实现

// 工具栏
Container(
  padding: const EdgeInsets.all(8),
  decoration: BoxDecoration(
    border: Border(bottom: BorderSide(color: Colors.grey.shade200)),
  ),
  child: Wrap(
    spacing: 8,
    children: [
      ElevatedButton.icon(
        onPressed: () => _insertMarkdownSyntax('# {}', placeholder: '一级标题'),
        icon: const Icon(Icons.title),
        label: const Text('H1'),
      ),
      ElevatedButton.icon(
        onPressed: () => _insertMarkdownSyntax('## {}', placeholder: '二级标题'),
        icon: const Icon(Icons.title),
        label: const Text('H2'),
      ),
      ElevatedButton.icon(
        onPressed: () => _insertMarkdownSyntax('### {}', placeholder: '三级标题'),
        icon: const Icon(Icons.title),
        label: const Text('H3'),
      ),
      ElevatedButton.icon(
        onPressed: () => _insertMarkdownSyntax('**{}**', placeholder: '粗体文本'),
        icon: const Icon(Icons.format_bold),
        label: const Text('粗体'),
      ),
      ElevatedButton.icon(
        onPressed: () => _insertMarkdownSyntax('*{}*', placeholder: '斜体文本'),
        icon: const Icon(Icons.format_italic),
        label: const Text('斜体'),
      ),
      // 其他按钮...
    ],
  ),
),

核心技术点分析：

语法插入：使用_insertMarkdownSyntax方法插入Markdown语法，提高编辑效率。
响应式布局：使用Wrap组件实现工具栏的响应式布局，在不同屏幕尺寸下自动调整按钮排列。
用户体验：提供直观的图标和标签，帮助用户快速找到所需的Markdown语法。

4.5 标签管理

4.5.1 添加标签

void _addTag() {
  showDialog(
    context: context,
    builder: (context) {
      final tagController = TextEditingController();
      return AlertDialog(
        title: const Text('添加标签'),
        content: TextField(
          controller: tagController,
          decoration: const InputDecoration(hintText: '输入标签名称'),
        ),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('取消'),
          ),
          TextButton(
            onPressed: () {
              if (tagController.text.isNotEmpty) {
                setState(() {
                  _tags.add(tagController.text);
                });
              }
              Navigator.pop(context);
            },
            child: const Text('添加'),
          ),
        ],
      );
    },
  );
}

核心技术点分析：

用户输入：使用AlertDialog和TextField获取用户输入的标签名称。
验证：使用if (tagController.text.isNotEmpty)验证标签名称是否为空。
状态更新：将新标签添加到标签列表中，并更新UI。

4.5.2 删除标签

void _removeTag(String tag) {
  setState(() {
    _tags.remove(tag);
  });
}

核心技术点分析：

状态更新：从标签列表中移除指定的标签，并更新UI。

4.6 搜索和过滤

4.6.1 搜索功能

TextField(
  onChanged: (value) {
    setState(() {
      _searchQuery = value;
    });
  },
  decoration: InputDecoration(
    hintText: '搜索笔记...',
    prefixIcon: const Icon(Icons.search),
    border: const OutlineInputBorder(
      borderRadius: BorderRadius.all(Radius.circular(8)),
    ),
  ),
),

核心技术点分析：

实时搜索：使用onChanged回调函数实时更新搜索查询。
状态更新：将搜索查询更新到应用状态中，触发笔记列表的重新过滤。

4.6.2 标签过滤

SizedBox(
  height: 40,
  child: ListView.builder(
    scrollDirection: Axis.horizontal,
    itemCount: _tags.length,
    itemBuilder: (context, index) {
      final tag = _tags[index];
      return Padding(
        padding: const EdgeInsets.only(right: 8),
        child: ElevatedButton(
          onPressed: () {
            setState(() {
              _selectedTag = tag;
            });
          },
          style: ElevatedButton.styleFrom(
            backgroundColor: _selectedTag == tag ? Colors.deepPurple : null,
          ),
          child: Text(tag),
        ),
      );
    },
  ),
),

核心技术点分析：

水平滚动：使用ListView.builder和scrollDirection: Axis.horizontal实现标签的水平滚动。
状态更新：将选中的标签更新到应用状态中，触发笔记列表的重新过滤。
视觉反馈：使用backgroundColor属性为选中的标签提供视觉反馈。

4.6.3 过滤逻辑

List<Note> _filterNotes() {
  var filteredNotes = _notes;
  if (_searchQuery.isNotEmpty) {
    filteredNotes = filteredNotes.where((note) =>
        note.title.toLowerCase().contains(_searchQuery.toLowerCase()) ||
        note.content.toLowerCase().contains(_searchQuery.toLowerCase())).toList();
  }
  if (_selectedTag != '全部') {
    filteredNotes = filteredNotes.where((note) => note.tags.contains(_selectedTag)).toList();
  }
  return filteredNotes..sort((a, b) => b.updatedAt.compareTo(a.updatedAt));
}

核心技术点分析：

搜索过滤：使用where方法根据搜索查询过滤笔记，支持标题和内容的搜索。
标签过滤：使用where方法根据选中的标签过滤笔记。
排序：使用sort方法根据更新时间对笔记进行排序，最新更新的笔记排在前面。

4.7 主题切换

IconButton(
  icon: Icon(_isDarkMode ? Icons.sunny : Icons.nightlight_round),
  onPressed: () => _saveDarkMode(!_isDarkMode),
),

Future<void> _saveDarkMode(bool value) async {
  final prefs = await SharedPreferences.getInstance();
  await prefs.setBool('dark_mode', value);
  setState(() {
    _isDarkMode = value;
  });
}

// 应用主题
MaterialApp(
  theme: _isDarkMode ? ThemeData.dark() : ThemeData.light(),
  home: Scaffold(
    // ...
  ),
),

核心技术点分析：

状态管理：使用_isDarkMode变量控制应用的主题模式。
持久化存储：使用shared_preferences存储用户的主题偏好，确保应用重启后保持用户的主题设置。
主题应用：使用MaterialApp的theme属性应用主题模式。

5. 技术深度解析

5.1 性能优化

惰性加载：使用ListView.builder实现笔记列表的惰性加载，只渲染可视区域的笔记，提高滚动性能。
状态管理：使用Flutter的setState管理应用状态，避免过度使用复杂的状态管理库，保持代码简洁。
数据存储：使用shared_preferences存储笔记数据，适合存储小型数据，避免了使用数据库的复杂性。
UI优化：使用Wrap组件实现工具栏的响应式布局，使用Card组件实现笔记卡片的美观展示。

5.2 用户体验优化

实时预览：提供Markdown实时预览功能，帮助用户快速了解渲染效果。
工具栏：提供常用Markdown语法的工具栏按钮，提高编辑效率。
标签管理：支持为笔记添加多个标签，方便分类管理。
搜索和过滤：支持通过关键词搜索和标签过滤，快速找到所需笔记。
主题切换：支持深色/浅色主题切换，适应不同的使用环境。
自动保存：在笔记编辑过程中自动保存，避免数据丢失。

5.3 代码组织

模块化：将应用分为笔记列表页面和笔记编辑页面，职责分明。
数据模型：将笔记数据封装为Note类，提供序列化和反序列化方法。
方法封装：将常用功能封装为方法，如_saveNotes、_loadNotes、_filterNotes等，提高代码复用性。
注释：添加适当的注释，提高代码可读性。

6. 鸿蒙平台适配

6.1 适配原理

flutter_markdown库在鸿蒙平台的适配主要涉及以下方面：

依赖管理：确保flutter_markdown库的依赖在鸿蒙平台上可用。
构建流程：适配鸿蒙平台的构建流程，确保应用能够正确构建和打包。
运行时环境：确保flutter_markdown库在鸿蒙运行时环境中正常工作。
网络访问：处理鸿蒙平台的网络访问权限，确保图片等网络资源能够正常加载。

6.2 适配步骤

添加鸿蒙平台支持：
```
flutter create --platforms=ohos .
```
配置鸿蒙依赖：
在ohos/oh-package.json5文件中添加必要的依赖。
配置网络权限：
在ohos/entry/src/main/module.json5文件中添加网络访问权限：
```
"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]
```
构建和运行：
```
flutter run -d ohos
```