Chrome Web环境下FlutterQuill工具栏插入图片（含URL）功能实现失败求助

核心问题 #

Chrome Web环境下，FlutterQuill默认未包含图片嵌入的Web专属Builder，必须手动配置对应组件才能支持图片（含URL）插入功能，否则会触发!kIsWeb. Please provide image EmbedBuilder for Web或Embeddable type 'image' is not supported by supplied embed builders错误。

具体修复步骤 #

1. 对齐依赖版本

确保pubspec.yaml中flutter_quill和flutter_quill_extensions的主版本一致，避免版本兼容问题：

dependencies:
  flutter:
    sdk: flutter
  flutter_quill: ^6.3.1
  flutter_quill_extensions: ^6.0.4

执行flutter pub get更新依赖。

2. 配置Web专属图片EmbedBuilder

在QuillEditor的embedBuilders中，除了通用的FlutterQuillEmbeds.builders()，必须针对Web环境添加QuillImageEmbedBuilderWeb：

QuillEditor(
  controller: _quillController,
  embedBuilders: [
    ...FlutterQuillEmbeds.builders(),
    if (kIsWeb) const QuillImageEmbedBuilderWeb(), // Web端专属配置
  ],
  // 其他编辑器配置（readOnly、padding等）
)

3. 配置工具栏的图片插入回调

为QuillToolbar启用图片按钮，并实现URL插入的逻辑：

QuillToolbar(
  controller: _quillController,
  embedButtons: FlutterQuillEmbeds.buttons(
    imageButtonOptions: QuillImageButtonOptions(
      // 处理URL插入请求
      onUrlInsertCallback: (url) async {
        if (url.trim().isEmpty) return false;
        final selection = _quillController.selection;
        // 将图片URL插入到编辑器光标位置
        _quillController.replaceText(
          selection.baseOffset,
          selection.extentOffset - selection.baseOffset,
          BlockEmbed.image(url),
          null,
        );
        return true;
      },
      // 若不需要本地图片上传，直接返回null即可
      onImagePickCallback: (file) async => null,
    ),
  ),
  // 其他工具栏配置（toolbarIconSize、color等）
)

完整可运行示例 #

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

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

  @override
  State<QuillWebImageEditor> createState() => _QuillWebImageEditorState();
}

class _QuillWebImageEditorState extends State<QuillWebImageEditor> {
  late final QuillController _quillController;

  @override
  void initState() {
    super.initState();
    _quillController = QuillController.basic();
  }

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Quill Web 图片编辑器')),
      body: Column(
        children: [
          // 编辑器工具栏
          QuillToolbar(
            controller: _quillController,
            embedButtons: FlutterQuillEmbeds.buttons(
              imageButtonOptions: QuillImageButtonOptions(
                onUrlInsertCallback: (url) async {
                  if (url.trim().isEmpty) return false;
                  final selection = _quillController.selection;
                  _quillController.replaceText(
                    selection.baseOffset,
                    selection.extentOffset - selection.baseOffset,
                    BlockEmbed.image(url),
                    null,
                  );
                  return true;
                },
                onImagePickCallback: (file) async => null,
              ),
            ),
          ),
          // 编辑器主体
          Expanded(
            child: QuillEditor(
              controller: _quillController,
              readOnly: false,
              autoFocus: false,
              embedBuilders: [
                ...FlutterQuillEmbeds.builders(),
                if (kIsWeb) const QuillImageEmbedBuilderWeb(),
              ],
              padding: const EdgeInsets.all(16),
              scrollable: true,
              focusNode: FocusNode(),
            ),
          ),
        ],
      ),
    );
  }
}

内容的提问来源于stack exchange，提问作者Minh Tiến Đào