Flutter富文本编辑器插件wysiwyg_flutter_quill_extensions的使用

Flutter富文本编辑器插件wysiwyg_flutter_quill_extensions的使用

flutter_quill 是一个富文本编辑器，它允许用户在编辑器中渲染自定义组件。wysiwyg_flutter_quill_extensions 是一个扩展插件，旨在通过添加更多功能（如图像、视频等）来增强 flutter_quill 的功能。

📚 目录

• 📝 关于
• 📦 安装
• 🛠 平台特定配置
• 🚀 使用
• ⚙️ 配置
• 🤝 贡献

📝 关于

flutter_quill 是一个富文本编辑器，它具有自定义嵌入构建器，允许你在编辑器中渲染自定义组件。这个扩展插件旨在通过添加更多功能（如图像、视频等）来增强其功能。

📦 安装

首先，遵循 flutter_quill 的安装指南。

在你的项目中添加 flutter_quill_extensions 依赖：

dependencies:
  flutter_quill_extensions: ^<最新版本>

或者，如果你需要使用最新的开发版本：

dependencies:
  flutter_quill_extensions:
    git:
      url: https://github.com/singerdmx/flutter-quill.git
      ref: v<最新版本>
      path: flutter_quill_extensions

🛠 平台特定配置

该包使用以下插件：

1. gal 用于保存图像。确保遵循开始指南，因为它需要平台特定的设置。
2. image_picker 用于选择图像。参见安装指南。
3. super_clipboard 仅在 Android 上需要一些设置，用于支持将图像复制到编辑器中以及非 Web 平台上富文本粘贴功能。参见Android 支持指南。对于 Android，minSdkVersion 需要为 23，因为 super_clipboard 需要它。

加载互联网上的图像

Android

1. 添加必要的权限到你的 AndroidManifest.xml。参见Android 指南或Flutter 网络指南。请注意，互联网权限默认只在调试模式下包含，你需要在发布版本中显式添加。
2. 如果需要限制图像和视频加载为 HTTPS，请相应地配置你的应用。如果需要支持 HTTP，请调整你的应用设置以适应发布模式。参见Android 清文本文通信指南。

macOS

在你的 Info.plist 文件中包含一个键以启用互联网访问。参见Flutter macOS 网络指南。

🚀 使用

一旦你完成了安装部分。在 QuillEditor 和 QuillToolbar 的配置中设置 embedBuilders 和 embedToolbar 参数。

Quill 工具栏

QuillToolbar.simple(
  configurations: QuillSimpleToolbarConfigurations(
    embedButtons: FlutterQuillEmbeds.toolbarButtons(),
  ),
),

Quill 编辑器

Expanded(
  child: QuillEditor.basic(
    configurations: QuillEditorConfigurations(
      embedBuilders: kIsWeb ? FlutterQuillEmbeds.editorWebBuilders() : FlutterQuillEmbeds.editorBuilders(),
    ),
  ),
)

⚙️ 配置

📦 嵌入块

flutter_quill 提供了一个接口，让所有用户都可以提供他们自己的嵌入块实现。这个包提供了图像、视频和公式嵌入块的实现。

嵌入块的使用说明可以在使用指南部分找到。

🔍 元素属性

当前库对图像和视频的支持有限，仅支持 width, height, margin 属性。

{
  "insert": {
    "image": "https://user-images.githubusercontent.com/122956/72955931-ccc07900-3d52-11ea-89b1-d468a6e2aa2b.png"
  },
  "attributes": {
    "style": "width: 50px; height: 50px; margin: 10px;"
  }
}

🔧 自定义元素属性

不适用于官方 Quill JS

定义 flutterAlignment 如下：

{
  "insert": {
    "image": "https://user-images.githubusercontent.com/122956/72955931-ccc07900-3d52-11ea-89b1-d468a6e2aa2b.png"
  },
  "attributes": {
    "style": "flutterAlignment: topLeft"
  }
}

这仅适用于非 Web 平台。

📝 富文本粘贴功能

富文本粘贴功能需要原生代码访问 Clipboard 数据作为 HTML，插件 super_clipboard 在所有平台（除了 Web）上都是必需的。

此包已经包含了 super_clipboard 并且会在内部使用它。要在 flutter_quill 中使用它，请在使用任何小部件或功能之前调用此函数：

FlutterQuillExtensions.useSuperClipboardPlugin();

super_clipboard 是一个全面的插件，提供了许多剪贴板功能，用于读取和写入富文本、图像和其他格式。

调用此函数将允许 flutter_quill 使用现代富文本功能来粘贴 HTML 和 Markdown，支持 GIF 文件和其他格式。

重要

在 Web 平台上，你只能在 paste 事件中从 Clipboard 获取 HTML，不需要 super_clipboard 或任何插件。粘贴功能不会使用标准粘贴快捷键逻辑工作。因此，你将无法在按钮或 Web 应用本身中使用富文本粘贴功能。你可以想出一种方法，在按下粘贴按钮时显示一个对话框，解释限制并显示他们需要按下的热键来粘贴，或者开发一个浏览器扩展来绕过此限制，类似于 Google 文档，并提供一个安装浏览器扩展的链接。参见问题 #1998 获取更多详细信息。

注意

我们仍在计划如何在问题 #1998 中实现这一点。

🖼️ 图像资产

如果你想在 Quill 编辑器中使用图像资产，必须确保你的资源文件夹是 assets，否则：

QuillEditor.basic(
  configurations: const QuillEditorConfigurations(
    // ...
    sharedConfigurations: QuillSharedConfigurations(
      extraConfigurations: {
        QuillSharedExtensionsConfigurations.key:
            QuillSharedExtensionsConfigurations(
          assetsPrefix: 'your-assets-folder-name', // 默认为 `assets`
        ),
      },
    ),
  ),
);

此信息对于包检查是否是其资产图像以使用 AssetImage 提供程序是必要的。

🎯 拖放功能

目前，拖放功能尚未正式支持，但你可以非常容易地通过以下步骤实现：

1. 拖放需要原生代码，你可以使用任何你喜欢的 Flutter 插件。如果你想要建议，我们推荐 desktop_drop，它最初是为桌面开发的。它支持 Web 以及 Android（iOS 不支持）。
2. 在你的 pubspec.yaml 中添加依赖项：

flutter pub add desktop_drop

并在你的 Dart 文件中导入它：

import 'package:desktop_drop/desktop_drop.dart';

1. 在 QuillEditor 的配置中，使用 builder 将编辑器包裹在 DropTarget 中，DropTarget 来自 desktop_drop：

import 'package:flutter_quill_extensions/flutter_quill_extensions.dart';

QuillEditor.basic(
  configurations: QuillEditorConfigurations(
    padding: const EdgeInsets.all(16),
    builder: (context, rawEditor) {
      return DropTarget(
        onDragDone: _onDragDone,
        child: rawEditor,
      );
    },
    embedBuilders: kIsWeb
        ? FlutterQuillEmbeds.editorWebBuilders()
        : FlutterQuillEmbeds.editorBuilders(),
  ),
)

1. 实现 _onDragDone，根据你的需求进行实现，这里只是一个简单的例子：

const List<String> imageFileExtensions = [
  '.jpeg',
  '.png',
  '.jpg',
  '.gif',
  '.webp',
  '.tif',
  '.heic'
];

OnDragDoneCallback get _onDragDone {
  return (details) {
    final scaffoldMessenger = ScaffoldMessenger.of(context);
    final file = details.files.first;
    final isSupported = imageFileExtensions.any((ext) => file.name.endsWith(ext));
    if (!isSupported) {
      scaffoldMessenger.showSnackBar(
        SnackBar(
          content: Text(
            'Only images are supported right now: ${file.mimeType}, ${file.name}, ${file.path}, $imageFileExtensions',
          ),
        ),
      );
      return;
    }
    // 要获取此扩展函数，请导入 flutter_quill_extensions
    _controller.insertImageBlock(
      imageSource: file.path,
    );
    scaffoldMessenger.showSnackBar(
      const SnackBar(
        content: Text('Image is inserted.'),
      ),
    );
  };
}