Flutter Quill 多编辑器共享控制器导致应用冻结问题解析

问题背景

在使用 Flutter Quill 富文本编辑器开发 Web 应用时，开发者遇到了一个棘手的问题：当在应用中动态添加多个 QuillEditor 组件并共享同一个 QuillController 时，应用程序会在用户尝试编辑第二个编辑器时完全冻结。这个问题在 Flutter Quill 的多个版本(9.3.6-9.3.9)中都存在，且在不同浏览器(Edge、Chrome)和 Flutter Web 环境下都能复现。

问题现象

具体表现为：

1. 第一个 QuillEditor 可以正常编辑
2. 添加第二个 QuillEditor 后，虽然可以获得焦点，但内容会与第一个编辑器同步
3. 当在第二个编辑器中尝试输入空格或其他内容时，整个应用会冻结
4. 开发者无法与任何应用组件交互，且控制台没有抛出任何错误或异常

技术分析

根本原因

问题的核心在于多个 QuillEditor 组件共享了同一个 QuillController 实例。QuillController 设计上应该是一对一服务于单个 QuillEditor 的，它管理着编辑器的状态、内容和操作历史。当多个编辑器共享同一个控制器时，会导致状态管理混乱，最终引发应用冻结。

设计缺陷

原实现中存在几个关键设计问题：

1. 使用同一个控制器管理多个编辑器
2. 直接在 setState 中动态添加 Widget 实例
3. 没有为每个编辑器维护独立的状态和焦点管理
4. 工具栏与多个编辑器共享控制器

解决方案

正确实现方式

1. 一对一控制器原则：每个 QuillEditor 必须拥有自己独立的 QuillController 实例。

2. 状态管理重构：应该管理编辑器内容数据而非 Widget 实例。推荐使用 ValueNotifier 或类似状态管理方案来维护编辑器内容列表。

3. 独立工具栏：每个编辑器应有自己的工具栏，或通过焦点检测动态切换工具栏关联的控制器。

4. 组件封装：将 QuillEditor 及其控制器封装为独立组件，内部管理自己的状态和焦点。

实现示例

class SectionEditor extends StatefulWidget {
  final String initialContent;
  
  const SectionEditor({required this.initialContent, super.key});

  @override
  State<SectionEditor> createState() => _SectionEditorState();
}

class _SectionEditorState extends State<SectionEditor> {
  late final QuillController _controller;
  late final FocusNode _focusNode;
  
  @override
  void initState() {
    super.initState();
    _controller = QuillController.basic();
    _focusNode = FocusNode();
    // 初始化内容
    _controller.document = Document.fromJson(jsonDecode(widget.initialContent));
  }
  
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        QuillToolbar.simple(
          configurations: QuillSimpleToolbarConfigurations(
            controller: _controller,
            sharedConfigurations: const QuillSharedConfigurations(
              locale: Locale('en'),
            ),
          ),
        ),
        QuillEditor.basic(
          configurations: QuillEditorConfigurations(
            controller: _controller,
            focusNode: _focusNode,
            readOnly: false,
            sharedConfigurations: const QuillSharedConfigurations(
              locale: Locale('en'),
            ),
          ),
        ),
      ],
    );
  }
  
  @override
  void dispose() {
    _controller.dispose();
    _focusNode.dispose();
    super.dispose();
  }
}

最佳实践建议

1. 避免共享控制器：QuillController 应该严格一对一服务于 QuillEditor。

2. 合理状态管理：使用状态管理方案(如 Provider、Riverpod 或 ValueNotifier)来维护编辑器内容列表，而非直接管理 Widget 实例。

3. 组件生命周期：确保在组件销毁时正确释放控制器和焦点节点资源。

4. 动态工具栏：实现一个智能工具栏，能够根据当前获得焦点的编辑器动态切换其关联的控制器。

5. 性能优化：对于大量编辑器的情况，考虑使用 ListView.builder 按需构建编辑器组件。

总结

Flutter Quill 是一个功能强大的富文本编辑器，但在多编辑器场景下需要特别注意控制器的管理。通过遵循一对一控制器原则、合理封装组件和采用正确的状态管理策略，可以避免应用冻结等问题，构建出稳定高效的富文本编辑功能。