Flutter-Quill 实现编辑器工具栏动态显示的最佳实践

前言

在富文本编辑器开发中，用户体验至关重要。Flutter-Quill 作为 Flutter 生态中功能强大的富文本编辑器组件，提供了丰富的定制能力。本文将详细介绍如何实现一个常见的交互需求：仅在用户点击编辑器时才显示工具栏，从而提供更简洁的界面体验。

核心实现思路

1. 状态管理方案

传统的 setState 方法在 Flutter-Quill 中可能无法完美工作，因为编辑器本身有复杂的焦点管理机制。更可靠的做法是：

• 使用 FocusNode 监听编辑器的焦点状态
• 结合 ValueNotifier 进行状态管理
• 通过 ValueListenableBuilder 实现响应式 UI 更新

2. 关键组件解析

FocusNode：这是 Flutter 中管理输入焦点的核心类，可以监听焦点的获取和失去事件。

ValueNotifier：轻量级的响应式状态管理工具，特别适合单一值的状态变更。

ValueListenableBuilder：根据 ValueNotifier 的变化自动重建 UI 的组件。

完整实现代码

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_quill/flutter_quill.dart';
import 'package:flutter_quill_extensions/flutter_quill_embeds.dart';

class DynamicToolbarEditor extends StatefulWidget {
  const DynamicToolbarEditor({super.key});

  @override
  State<DynamicToolbarEditor> createState() => _DynamicToolbarEditorState();
}

class _DynamicToolbarEditorState extends State<DynamicToolbarEditor> {
  final ValueNotifier<bool> _showToolBar = ValueNotifier(false);
  final QuillController _controller = QuillController.basic();
  late final FocusNode _focusNode;

  @override
  void initState() {
    super.initState();
    _focusNode = FocusNode()..addListener(() {
      _showToolBar.value = _focusNode.hasFocus;
    });
  }

  @override
  void dispose() {
    _focusNode.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Container(
      height: 300,
      clipBehavior: Clip.antiAlias,
      padding: const EdgeInsets.symmetric(vertical: 3),
      decoration: BoxDecoration(
        borderRadius: BorderRadius.circular(7),
        border: Border.all(
          color: Colors.grey,
          width: 1,
        ),
      ),
      child: Column(
        children: [
          ValueListenableBuilder<bool>(
            valueListenable: _showToolBar,
            builder: (context, showToolbar, _) => showToolbar
                ? QuillToolbar.simple(
                    configurations: QuillSimpleToolbarConfigurations(
                      embedButtons: FlutterQuillEmbeds.toolbarButtons(),
                      controller: _controller,
                    ),
                  )
                : const SizedBox.shrink(),
          ),
          Expanded(
            child: QuillEditor.basic(
              focusNode: _focusNode,
              configurations: QuillEditorConfigurations(
                autoFocus: false,
                controller: _controller,
                embedBuilders: kIsWeb
                    ? FlutterQuillEmbeds.editorWebBuilders()
                    : FlutterQuillEmbeds.editorBuilders(),
              ),
            ),
          )
        ],
      ),
    );
  }
}

技术要点详解

1. 初始化阶段：

   • 创建 FocusNode 并添加监听器
   • 当焦点状态变化时更新 ValueNotifier 的值

2. UI构建阶段：

   • 使用 ValueListenableBuilder 监听工具栏显示状态
   • 将 FocusNode 传递给 QuillEditor 组件
   • 设置 autoFocus 为 false 避免初始自动获取焦点

3. 资源释放：

   • 在 dispose 方法中正确释放 FocusNode
   • 遵循 Flutter 最佳实践避免内存泄漏

进阶优化建议

1. 动画效果：可以为工具栏的显示/隐藏添加动画效果，提升用户体验。

2. 键盘处理：在移动端，需要考虑软键盘弹出时的布局调整。

3. 自定义样式：通过 QuillToolbarConfigurations 可以完全自定义工具栏的外观和功能。

4. 多编辑器管理：如果有多个编辑器实例，需要为每个实例创建独立的 FocusNode。

常见问题解决

1. 工具栏不显示：

   • 检查 FocusNode 是否正确绑定
   • 确认 ValueNotifier 的值是否正确更新
   • 验证监听器是否被正确添加

2. 焦点管理冲突：

   • 避免在多个组件间共享 FocusNode
   • 确保 dispose 时正确释放资源

3. 性能问题：

   • 对于复杂文档，考虑使用 const 构造函数优化重建性能
   • 避免在 builder 中进行耗时操作

总结

通过本文介绍的方法，开发者可以优雅地实现 Flutter-Quill 编辑器的动态工具栏功能。这种实现方式不仅符合 Flutter 的状态管理最佳实践，还能提供流畅的用户体验。关键在于正确使用 FocusNode 和响应式编程范式，这也是 Flutter 开发中的通用技巧，可以应用于其他需要根据输入状态变化 UI 的场景。