Flutter QuillEditor在ListView中无法跟随光标自动滚动问题

问题描述 #

当前布局里，QuillEditor设置expands: false时，编辑文本时光标无法自动滚动到屏幕可视区域，没法像普通TextField那样跟随光标自动滚动；要是把expands设为true，会触发无限高度错误，就算用Expanded或Flexible包裹也解决不了；用固定高度容器只能实现编辑器内部滚动，不符合整页滚动的需求。

解决方案 #

方案一：监听光标变化，联动外层ListView滚动 #

通过监听Quill编辑器的光标位置变化，手动控制外层ListView的滚动，让光标始终处于可视区域。

1. 给外层ListView绑定ScrollController，给QuillEditor添加GlobalKey：

final outerScrollController = ScrollController();
final editorKey = GlobalKey();

// 外层ListView的controller设置为outerScrollController
ListView(
  controller: outerScrollController,
  children: [
    // ... 其他组件
    QuillEditor(
      key: editorKey, // 添加key
      // ... 原有属性
    ),
  ],
)

2. 在页面初始化时添加光标和焦点监听，实现自动滚动：

@override
void initState() {
  super.initState();
  // 监听文档变化，触发滚动
  contentController.document.onChange.listen((_) => _scrollToCursor());
  // 监听焦点获取，确保光标可见
  contentFocusNode.addListener(() {
    if (contentFocusNode.hasFocus) _scrollToCursor();
  });
}

Future<void> _scrollToCursor() async {
  await Future.delayed(const Duration(milliseconds: 100)); // 等待UI更新完成
  final editorRenderBox = editorKey.currentContext?.findRenderObject() as RenderBox?;
  if (editorRenderBox == null) return;

  // 获取光标在编辑器内的本地偏移
  final localOffset = contentController.getLocalOffsetForCaret(contentController.selection);
  // 转换为全局坐标
  final globalOffset = editorRenderBox.localToGlobal(localOffset);
  final screenHeight = MediaQuery.of(context).size.height;
  final outerOffset = outerScrollController.offset;
  final cursorY = globalOffset.dy - outerOffset;

  // 判断光标是否在可视区域内，不在则滚动调整
  const topMargin = 100;
  const bottomMargin = 200;
  if (cursorY < topMargin || cursorY > screenHeight - bottomMargin) {
    outerScrollController.animateTo(
      globalOffset.dy - screenHeight / 2,
      duration: const Duration(milliseconds: 200),
      curve: Curves.easeInOut,
    );
  }
}

方案二：调整布局为CustomScrollView，合并滚动逻辑 #

把外层ListView替换为CustomScrollView，关闭QuillEditor自身的滚动，让整体布局由CustomScrollView统一处理滚动，再配合光标监听实现自动滚动。

1. 替换布局结构：

CustomScrollView(
  controller: outerScrollController,
  slivers: [
    SliverPadding(
      padding: const EdgeInsets.fromLTRB(20, 10, 20, 10),
      sliver: SliverList(
        delegate: SliverChildListDelegate([
          TextField(/* 原有属性 */),
          Original.Text(/* 原有属性 */),
          QuillEditor(
            controller: contentController,
            readOnly: !owner!,
            autoFocus: false,
            placeholder: "Contenuto",
            customStyles: /* 原有属性 */,
            expands: false,
            focusNode: contentFocusNode,
            padding: EdgeInsets.zero,
            scrollable: false, // 关闭编辑器自身滚动
            // 其他原有属性
          ),
        ]),
      ),
    ),
  ],
)

2. 同样使用方案一中的_scrollToCursor方法和监听逻辑，确保光标滚动到可视区域。

说明 #

两种方案都能实现整页滚动且光标自动跟随的效果：

• 方案一适合保留原有ListView布局结构，仅通过监听调整滚动；
• 方案二通过CustomScrollView优化布局，让整体滚动更流畅，适合复杂页面场景。

内容的提问来源于stack exchange，提问作者aleee