Flutter-Quill项目深度解析：实现自定义嵌入块功能-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00547/article/details/148782957

Flutter-Quill项目深度解析：实现自定义嵌入块功能

flutter-quill Rich text editor for Flutter 项目地址: https://gitcode.com/gh_mirrors/fl/flutter-quill

引言

在富文本编辑器的开发中，我们经常需要超越纯文本的限制，嵌入各种自定义内容。Flutter-Quill作为一款强大的富文本编辑器组件，提供了灵活的扩展机制，允许开发者创建自定义嵌入块(Custom Embed Blocks)。本文将深入探讨如何在Flutter-Quill中实现这一功能。

什么是自定义嵌入块

自定义嵌入块是指可以在富文本编辑器中插入的非标准内容单元，它们可以是：

笔记或注释
交互式小部件
多媒体内容
任何开发者需要的内置组件

实现步骤详解

1. 创建自定义块嵌入类

首先需要定义一个继承自CustomBlockEmbed的类，这个类负责数据的序列化和反序列化：

class NotesBlockEmbed extends CustomBlockEmbed {
  const NotesBlockEmbed(String value) : super(noteType, value);

  static const String noteType = 'notes';

  static NotesBlockEmbed fromDocument(Document document) =>
      NotesBlockEmbed(jsonEncode(document.toDelta().toJson()));

  Document get document => Document.fromJson(jsonDecode(data));
}

关键点解析：

noteType是嵌入块的唯一标识符
fromDocument方法将富文本文档转换为可存储的格式
document getter方法实现数据的反向解析

2. 构建嵌入块小部件

接下来需要创建实际的Flutter小部件来展示嵌入内容：

class NotesEmbedBuilder extends EmbedBuilder {
  NotesEmbedBuilder({required this.addEditNote});

  final Future<void> Function(BuildContext context, {Document? document}) addEditNote;

  @override
  String get key => 'notes';

  @override
  Widget build(BuildContext context, EmbedContext embedContext) {
    final notes = NotesBlockEmbed(embedContext.node.value.data).document;

    return Material(
      color: Colors.transparent,
      child: ListTile(
        title: Text(
          notes.toPlainText().replaceAll('\n', ' '),
          maxLines: 3,
          overflow: TextOverflow.ellipsis,
        ),
        leading: const Icon(Icons.notes),
        onTap: () => addEditNote(context, document: notes),
        shape: RoundedRectangleBorder(
          borderRadius: BorderRadius.circular(10),
          side: const BorderSide(color: Colors.grey),
        ),
      ),
    );
  }
}

设计考虑：

使用ListTile提供良好的触摸反馈
限制文本显示行数并添加省略号
圆角边框增强视觉体验
透明背景确保与编辑器无缝融合

3. 实现添加/编辑功能

核心交互逻辑处理：

Future<void> _addEditNote(BuildContext context, {Document? document}) async {
  final isEditing = document != null;
  final controller = QuillController(
    document: document ?? Document(),
    selection: const TextSelection.collapsed(offset: 0),
  );

  await showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: Row(
        children: [
          Text('${isEditing ? 'Edit' : 'Add'} note'),
          IconButton(
            onPressed: () => Navigator.of(context).pop(),
            icon: const Icon(Icons.close),
          )
        ],
      ),
      content: QuillEditor.basic(
        controller: controller,
        config: const QuillEditorConfig(),
      ),
    ),
  );

  if (controller.document.isEmpty()) return;

  final block = BlockEmbed.custom(
    NotesBlockEmbed.fromDocument(controller.document),
  );
  
  if (isEditing) {
    final offset = getEmbedNode(controller, controller.selection.start).offset;
    controller.replaceText(offset, 1, block, TextSelection.collapsed(offset: offset));
  } else {
    controller.replaceText(controller.selection.start, 0, block, null);
  }
}

关键逻辑：

区分新建和编辑模式
使用对话框提供编辑界面
空内容检查
精确的文本替换操作

实际应用效果

实现后的自定义笔记嵌入块会显示为带有图标的可点击区域，点击后可以编辑富文本内容。在编辑器中，它会以紧凑的形式展示内容预览，保持界面的整洁性。

高级技巧与最佳实践

性能优化：
- 对于复杂嵌入块，考虑使用AutomaticKeepAliveClientMixin
- 实现didUpdateWidget以优化重建性能
数据安全：
- 对序列化数据进行校验
- 添加版本控制字段以便未来扩展
交互设计：
- 考虑添加拖拽调整大小功能
- 实现多状态交互（如折叠/展开）
样式定制：
- 通过主题系统统一风格
- 支持动态样式切换