Quill Blot Formatter 2 (quill-blot-formatter2)

quill 模块 quill-blot-formatter 的更新版本，使对齐功能兼容 Quill V2。开箱即支持调整图像和 iframe 视频的大小及重新对齐。对于图像，支持链接管理以及编辑 alt 和 title 值。可通过 BlotSpec 和 Action 轻松扩展。

[!WARNING] 本 README 仅适用于 v3.x - 请参阅 NPM 获取旧版本文档

the new toolbar with alt title editing button

[!IMPORTANT] 在使用此包之前，建议至少熟悉 Actions、CSS 和 Options 中涵盖的信息。如果你的 Quill 编辑器可滚动，请务必阅读 Scrollable Editors 中的说明。

[!WARNING] 此包专为原生 Quill 编辑器设计，并已针对其进行测试。它未针对 Vue 或 Angular 的 Quill 包装包进行测试。如果你使用这些包并遇到问题，我欢迎经过充分测试的 PR 来解决该问题，但我无法支持所有这些包。如果你能让它与这些包配合使用，并有一些相关提示，我也很乐意在此处包含这些内容。

[!CAUTION] 请注意，BlotFormatter2 不兼容 React 包装库（react-quilljs）。请参阅下方 Demos 中关于使用原生 Quill 对象配合 Blotformatter2 和 React 的可用示例。

新功能

版本 3.2

添加了静态方法，用于预注册 ImageAlign 和 IframeAlign 格式，以便在启动时包含在 Quill formats 配置规范中。有关更多信息，请参阅与 formats 配置一起使用。

模块解析已从 Node16 更新为 NodeNext。

版本 3.1

添加了 .cjs 输出并修复了默认导出。

使用 require 的语法从：

const BlotFormatter = require('quill-blot-formatter2').default;

变为

const BlotFormatter = require('quill-blot-formatter2');

.default 仍然有效，以保持向后兼容性。

版本 3.0

[!CAUTION] 虽然此版本在功能上只有细微变化，但底层有重大变更，并且构建路径也发生了变化。如果您正在升级，并且在此包中进行了大量修改，请在投入生产环境之前进行彻底测试。如果您修改了 align format attributor 类，这一点尤为重要。

ESM (es2022) 构建输出现在可用，见 index.ems.js。
UMD 构建已重命名为 index.js。详见 Installation。
现在会为每个构建输出对应的 map 文件，并且代码中已添加 doc-string，以便于开发/扩展 BlotFormatter。
项目现在使用 vite 编译，webpack 已停止使用。
对全局 Quill 对象的内部引用已替换为 quill 实例构造函数。这应该能解决之前版本中与 React（但不包括 react-quilljs 包装器）或 Angular & Vue 一起使用时的问题。
现在可以通过设置选项 debug: true 进行调试 - 这是一种详细模式，输出到调试控制台。
在大多数情况下，如果激活格式化器覆盖层时工具栏被隐藏，格式化器工具栏现在会滚动到可见区域。
可选的 Quill 提示框修复会将 Quill 的原生提示框限制在 Quill 编辑器元素的边界内。这旨在用于可滚动的编辑器，因为在某些情况下，如果提示框显示在此矩形之外，Quill 会导致裁剪。
v3.0.1 添加了选项 image: { autoHeight: boolean }。当设置为 false 时，图像高度将以 px 为单位设置，而非默认的 auto - 满足 PDF 输出的要求。
v3.0.2 添加了启用状态，以镜像 Quill 编辑器的启用状态。当 enabled 为 false 时，禁用格式化器并隐藏视频代理图像。

Version 2.4

新增操作：

Link Action 允许直接从格式化工具栏编辑图片上的超链接。更多信息
Caret Action 引入使用左右箭头取消选择格式化器的功能，并将光标放置在图片之前或之后的相应编辑器位置。更多信息

其他改进：

工具栏按钮现在具有工具提示（通过 title 属性）。可通过选项配置：toolbar.tooltips。每个键应与相应的操作名称匹配。参见 DefaultOptions 以获取示例。
工具栏按钮的激活样式现在通过选项 toolbar.buttonSelectedStyle 和 toolbar.buttonSelectedClassName 配置
更改了通过鼠标点击取消选择的行为，使得如果直接点击覆盖层的左侧或右侧，光标将放置在上一/下一位置。
改进了 Alt/Title 模态框表单的默认样式。

Version 2.3

功能方面，这是一个次要更新，允许图片上的空 alt 标签。之前如果遇到这些标签会被移除。

此版本对依赖项和目标编译器模块进行了升级：tsconfig.compilerOptions.module 从 commonjs 更新到 es2022。

Version 2.2

此版本是一次重大重写，包括：

支持移动/触摸屏幕（包括通过捏合手势调整大小）
相对尺寸与绝对尺寸（% 与 px），可选择在所有调整大小操作中使用，或通过工具栏按钮按 blot 单独更改
尺寸信息内嵌，用于精确调整大小以及在调整大小过程中提供交互式反馈
支持可滚动编辑器
修复了许多从原始 blot-formatter 包中遗留的 bug

size information display

Version 2.2.2

添加了 compress 操作，以在适用时减小嵌入图像的大小
Resize Action 的可选 imageOversizeProtection 设置可防止在使用绝对尺寸时，图像尺寸大于其原始尺寸

compress action

请参阅 change log 以获取完整详情。

Version 2.1

此版本为图片添加了 alt 和 title 编辑支持。请在覆盖工具栏的对齐按钮旁边查找 T 按钮。

点击 T 按钮将打开一个模态表单以添加您的值。

the alt/title editing modal form

使用建议的 css，标题也可以用作图片的说明文字。

a floating image with caption from title attribute

请参阅下方关于用法、css 以及重要地，在 Quill 中支持图片标题的说明。

安装

[!WARNING] 版本 3 中的安装和使用说明发生了重大变化。如果您使用的是之前的版本，建议升级到 3 或更高版本，特别是对于 React、Angular 等用户。

[!CAUTION] 此包不兼容 React 包装库（react-quilljs）。请参阅下方演示，其中包含使用原生 Quill 配合 BlotFormatter2 和 React 的可用示例。

通过 npm 安装该包：

npm install @enzedonline/quill-blot-formatter2

使用示例

Node.js / CommonJS

const BlotFormatter = require('@enzedonline/quill-blot-formatter2');
// or for named exports (for example, Options):
const { Options } = require('@enzedonline/quill-blot-formatter2');

ESM（React、Next.js、Angular、Vue、Vite 等）

import BlotFormatter from '@enzedonline/quill-blot-formatter2';
// or for named exports (for example, Options):
import { Options } from '@enzedonline/quill-blot-formatter2';

:warning: 请勿将 react-quilljs 包装器与 BlotFormatter 结合使用，它们不兼容。参见 Demos。

Angular

如上所述将其添加到项目中，然后在组件或服务中导入：

import BlotFormatter from '@enzedonline/quill-blot-formatter2';

React / Next.js

在组件或模块中导入：

import BlotFormatter from '@enzedonline/quill-blot-formatter2';

在 `<script type="module">` 中使用 ESM（浏览器）

<script type="module">
  import BlotFormatter from 'https://cdn.jsdelivr.net/npm/@enzedonline/quill-blot-formatter2@3.0/dist/index.esm.js';
  // Use BlotFormatter here
</script>

在 `<script>` 标签中使用 UMD（浏览器）

<script src="https://cdn.jsdelivr.net/npm/@enzedonline/quill-blot-formatter2@3.0/dist/index.js"></script>
<script>
  // The global variable is QuillBlotFormatter2
  const BlotFormatter = QuillBlotFormatter2.default;
  // Use BlotFormatter here
</script>

在 Quill 中注册 Blotformatter

在创建 Quill 编辑器实例之前注册 BlotFormatter。

Quill.register('modules/blotFormatter2', BlotFormatter);
const quill = new Quill("#quill-editor", {
    modules: {
        ....,
        blotFormatter2: {
          // options
        }
    },
    ....
});

使用建议的对齐格式样式

通过导入（React 等）

import "@enzedonline/quill-blot-formatter2/dist/css/quill-blot-formatter2.css"; // align styles

通过 CDN

<link 
  rel="stylesheet" 
  href="https://cdn.jsdelivr.net/npm/@enzedonline/quill-blot-formatter2/dist/css/quill-blot-formatter2.css"
>

与 formats 配置配合使用

如果您使用 Quill formats 配置来自定义编辑器识别的格式，则需要预先注册 BlotFormatter2 所使用的格式（ImageAlign 和 IframeAlign）。这些格式会在 Blotformatter2 启动时自动注册，但为了让 formats 配置能够识别它们，必须在启动前完成注册。

有 3 个静态方法可以实现这一点：

Blotformatter.registerImageAlign(Quill) 注册 ImageAlign
Blotformatter.registerIframeAlign(Quill) 注册 IframeAlign
Blotformatter.registerFormats(Quill) 调用上述两者

注意，您必须提供 Quill 对象，而不是 quill 实例。

将 true 作为第二个参数传入，以在控制台打印调试信息。

例如 UMD

  const BlotFormatter = QuillBlotFormatter2.default;
  BlotFormatter.registerFormats(Quill);
  Quill.register('modules/blotFormatter2', BlotFormatter);
  const quill = new Quill("#quill-editor", {
    ...
    formats: ["bold", "image", "video", "iframeAlign", "imageAlign"],
    ...
  })

或 ESM

  import Quill from 'https://cdn.skypack.dev/quill@2.0.3';
  import QuillBlotFormatter2 from '.../index.esm.js';
  QuillBlotFormatter2.registerFormats(Quill);
  Quill.register('modules/blotFormatter2', QuillBlotFormatter2);
    const quill = new Quill("#quill-editor", {
    ...
    formats: ["bold", "image", "video", "iframeAlign", "imageAlign"],
    ...
  })

演示

Script Tag - 在 script 标签中使用 Quill 和 BlotFormatter2 的 UMD 构建版本。
Script Module - 在 script 模块中使用 Quill 和 BlotFormatter2 的 ESM 构建版本。
React - 在 React 中使用 Quill 和 BlotFormatter2。此示例展示了如何在 React 中使用原生 Quill 对象，并避免包装库带来的 bug（react-quilljs）。
Vite - fork 或 clone 此仓库，并使用 npm run dev 运行此站点，或者复制这些 html 文件并修改导入以在您的环境中运行。

操作

共有三个常用操作，以及针对图像 blot 的另外三个操作。这些操作通过以下选项启用：

blotFormatter2: {
  align: {
    allowAligning: true, // default true
  },
  resize: {
    allowResizing: true, // default true
  },
  delete: {
    allowKeyboardDelete: true, // default true
  },
  image: {
    allowAltTitleEdit: true, // default true
    allowCompressor: true, // default false, enable with true
    linkOptions: {
      allowLinkEdit: true //default true
    }
  }
}

将值设置为 false 以禁用 action。

除 allowCompressor 外，所有这些默认均设置为 true。

对齐操作

此操作处理 blot 的对齐。

[!IMPORTANT] 为了使对齐对渲染的 HTML 产生效果，您必须包含相关的 CSS 来处理这些格式。有关更多详细信息，请参阅下方的 CSS 部分。

此包注册了两个用于对齐 blot 的 Quill 格式：IframeAlign 和 ImageAlign

对齐和放置由 CSS 类处理，图像和 iframe 各有一套：

.ql-image-align-left, .ql-image-align-center, .ql-image-align-right,
.ql-iframe-align-left, .ql-iframe-align-center, .ql-iframe-align-right

对于图像，这些类应用于 Quill 的 <span> 包装器，而不是图像本身。

对于图像和 iframe，都会添加一个辅助属性 data-blot-align，其值为对齐方式（即 'left'、'center' 或 'right'）。

对齐后的 blot 的宽度是样式辅助函数（data-relative-size 和 --resize-width）所必需的 - 有关这些的更多信息，请参阅下方的 Resize 部分。如果 blot 没有 width 属性，将使用以下内容：

对于图像，将使用图像的自然宽度（以 px 为单位）
对于 iframe，将使用当前显示的宽度（以 px 为单位）

实际应用的格式由 scope 决定 - 图像为 inline，iframe 为 block。如果由于某种原因，你使用了具有 block scope 的自定义图像 blot，它将使用 .ql-iframe-align-xx 进行格式化。

[!TIP] Quill 文档错误地扩展了 BlockEmbed 来创建 ImageBlot。如果你使用自定义的 Image blot，正确的扩展类是 blots/Embed。

Options

Align 有两个选项：

  align: {
    allowAligning: true,
    alignments: ['left', 'center', 'right']
  },

allowAligning: boolean - 开启或关闭对齐。如果为 false，工具栏中不会添加对齐按钮。默认值为 true。
alignments: string[] - 要使用的对齐方式 - 必须与工具栏图标名称匹配，并且是 align 格式白名单的成员。默认值为 ['left', 'center', 'right']。

[!IMPORTANT] 在 2.2 中更新

toolbar 和 icons 选项已从选项的 align 分支移至其自身的 toolbar 选项类别（见下文）。

如果从 2.0/2.1 升级并使用新的 CSS，在某些情况下可能需要重新应用对齐格式。有关在过渡期间同时使用旧版和新版 CSS 的详细信息，请参阅 CSS 部分。

Resize Action

负责处理 blot 的缩放以及显示尺寸信息。请注意，blot 无法被缩放为大于 Quill 编辑器中可用显示宽度的宽度。

缩放 blot 时会添加以下属性：

width：根据选项，blot 的像素或百分比尺寸
height：blot 的高度 - 在所有情况下均为 auto，除非使用绝对尺寸缩放 iframe 且没有可用的 aspect-ratio。

以下内容应用于对齐的图片 span 包装器以及直接应用于 iframe。它们纯粹用于构建 CSS 选择器和规则，以辅助样式设置。

data-relative-size 布尔值，反映 blot 是否已使用 px 或 % 进行尺寸设置。
style: --resize-width 字符串，blot 宽度属性的副本。可用于设置图片对齐 span 包装器的宽度，也可用于在响应式网站上有条件地缩放元素。对于图片，仅当设置了对其时才会添加此属性。

尺寸信息显示

size information display

在叠加层处于激活状态时，按住鼠标或触摸叠加层以显示尺寸。松开以关闭显示。

如果使用相对尺寸，相对尺寸将与当前绝对显示尺寸一起显示在括号中。

如果使用绝对尺寸，且当前显示尺寸与宽度属性值不同（例如，宽度值大于编辑器宽度），则基于宽度属性的尺寸将首先显示，当前显示尺寸显示在括号中。

size information display

如果未设置 blot 的宽度，且该 blot 是图像，则显示图像尺寸（如果当前显示尺寸不同，则同时显示当前显示尺寸）。

在调整大小期间，尺寸信息框将处于激活状态，以提供交互式反馈。

可以通过 options.overlay.sizeInfoStyle 对尺寸信息框进行样式设置。

选项

最可能感兴趣的五个设置：

  resize: {
    allowResizing: true,
    allowResizeModeChange: false,
    useRelativeSize: false,
    imageOversizeProtection: false,
    minimumWidthPx: 25,
  },

allowResizing: boolean: 允许调整 blot 的大小。将此设置为 false 会在格式化覆盖层激活时阻止加载 Resize 操作。这将禁用覆盖层角落的拖动手柄，并且不会加载处理大小调整的事件监听器。
allowResizeModeChange: boolean: 在工具栏上显示 % 按钮。点击此按钮可在绝对大小和相对大小模式之间切换。有关更多详细信息，请参阅 Using Relative Sizes。如果 allowResizing 为 false，则不会加载 Resize 操作，并且 % 按钮将不可用。
useRelativeSize: boolean: 如果 true，则根据 allowResizeModeChange 设置的值，默认使用相对大小或对所有大小调整操作使用相对大小。有关更多详细信息，请参阅 Using Relative Sizes。
imageOversizeProtection: boolean^{:warning:New in 2.2.2}: 当设置为 true 时，防止图像被调整得比其自然宽度更大，以防止图像质量下降。这仅适用于大小调整模式为绝对值（px）而非相对值（%）的情况。如果图像 src 是 svg（无论是嵌入的还是链接的），则该图像不受此限制。
minimumWidthPx: number: 在大小调整操作期间，blot 可以缩小到的最小宽度（px）。

此外，handleClassName 和 handleStyle 可用于控制拖动手柄的样式（参见 Options）

Using Relative Sizes

版本 2.2 引入了相对大小作为选项。如果使用，大小将设置为 Quill 编辑器可用宽度（quill.root 宽度减去水平内边距）的比例。

blot 必须被调整大小（即具有宽度属性）才能使用相对大小。

相对大小设置默认未启用。

[!IMPORTANT] 无论设置如何，blot 在调整大小之前都会保留其原始/当前的宽度属性单位。 除非先调整大小或主动使用模式切换 % 按钮，否则 blot 的大小设置不会从绝对值变为相对值（或反之）。唯一的例外是使用 allowResizeModeChange = false 和 useRelativeSize = true 对齐未设置大小的图像——在这种情况下，图像将根据其自然宽度相对于编辑器宽度的比例（最高 100%）设置相对大小。

有两种方法可以应用规则以使用相对（或绝对）大小设置。

使用 `allowResizeModeChange = false`：

工具栏中没有用于更改大小模式的 % 按钮（默认设置）。

useRelativeSize = false - 任何调整大小操作都会以像素为单位设置宽度属性。这是默认设置。

useRelativeSize = true - 任何调整大小操作都会以 % 为单位设置宽度属性，作为编辑器宽度（减去内边距）的比例。使用此设置对齐未设置大小的图像会将图像宽度设置为相对值。

使用 `allowResizeModeChange = true`：

工具栏中存在一个 % 按钮，用于在绝对和相对大小模式之间切换。

使用 allowResizeModeChange = true 时，useRelativeSize 设置仅应用于尚未具有宽度属性的 blot。现有宽度属性的大小模式将保持不变。例如，使用 useRelativeSize = true 调整具有 px 宽度属性的 blot 的大小不会更改大小模式。然后，您可以使用 % 按钮更改大小模式。

当从绝对大小更改为相对大小时，您可能会注意到 blot 上的显示大小有轻微变化。相对大小会四舍五入到最接近的整数百分比，这可能导致显示的宽度略微向上或向下调整。

在触摸屏上调整大小 :warning:2.2 版本新增

通过捏合手势在触摸屏上调整 blot 的大小：在格式化器覆盖层处于活动状态时，用两根手指触摸覆盖层，通过张开/收拢手指来控制大小

拖动手柄在触摸屏上响应不佳，建议使用捏合手势。

删除操作

当覆盖层处于活动状态时，按下删除键或退格键将删除底层的 blot。

选项

要禁用删除操作，请使用以下设置：

  delete: {
    allowKeyboardDelete: false,
  },

属性操作（仅限图像 blot）

从 2.1 版本开始，alt 和 title 图像属性可以通过覆盖层工具栏上的 T 按钮进行编辑。

the attribute action alt/title modal form

[!CAUTION] :exclamation: 关于 Quill 和图片标题的重要说明 :exclamation:

在撰写本文时，Quill 的当前版本（v2.0.3）并不原生支持在图片 delta 中存储 title 属性。因此，当你重新加载编辑器时，title 属性将会丢失。有一个 Quill pull request 旨在解决此问题。

此包包含一个更新后的 Image blot，以解决此问题。

要使用该更新后的 blot，只需在你的 blotFormatter2 选项中包含以下内容：
  image: {
      registerImageTitleBlot: true
  }
这并非默认启用，因为这可能会覆盖你可能正在使用的任何自定义 Image blot。

如果你使用自定义 image blot，请从你的选项中省略 registerImageTitleBlot，并确保将 title 添加到受支持的属性中。

Options

要禁用 alt/title 编辑，请使用以下选项（默认 true）：

  image: {
    allowAltTitleEdit: false,
  },

alt/title 模态框在样式、图标和标签文本方面是可定制的（:warning:2.2.1 新增）：

image: {
  altTitleModalOptions: {
    styles: {
      modalBackground: { [key: string]: any } | null | undefined; // screen background mask
      modalContainer: { [key: string]: any } | null | undefined;; // modal dialog
      label: { [key: string]: any } | null | undefined;           // form labels
      textarea: { [key: string]: any } | null | undefined;        // textareas
      submitButton: { [key: string]: any } | null | undefined;    // submit button
      cancelButton: { [key: string]: any } | null | undefined;    // cancel button
    };
    icons: {
      // inner html for buttons (svg recommended)
      submitButton: string; 
      cancelButton: string;
    };
    labels: {
      // text for labels (for multi-lang support)
      alt: string;
      title: string;
    };
  }
}

Styles

除非指定了 null，否则上述指定的任何样式都会与默认样式合并，在这种情况下，渲染的模态框中将不包含 style 属性。你还可以指定 styles: null 以移除模态框中的所有内联样式。如果你更喜欢使用 CSS 来设置模态框的样式，可以在选择器中使用 div[data-blot-formatter-modal] 来定位渲染的模态框元素。

Icons

指定按钮的 svg 字符串表示（不包含 width/height 属性）或其他合适的 inner HTML。

Labels

对于多语言站点，您可以在选项中更改模态框表单的标签。例如：

image: {
  altTitleModalOptions: {
    labels: {
      alt: "Alt tekst",
      title: "Bildetittel",
    };
  }
}

使用标题作为说明文字

对于对齐的图片（假设您的图片块是内联的），图片标题会被复制到包裹的 <span> 标签的 data-title 属性中。

<span class="ql-image-align-center" 
  data-title="some image title"
  data-relative-size="true" 
  style="--resize-width: 50%;">
  <img src="https://example.com/media/images/some-image.png" 
    alt="some alt text" 
    data-blot-align="center"
    title="some image title"
    width="25%" height="auto">
</span>

您可以利用 data-title 属性，使用下方建议的 css 来显示标题。

压缩操作（仅限嵌入式图像斑点）

:warning: 2.2.2 版本新增

压缩操作将减小符合缩减条件的嵌入式图像的大小。

compressor action

[!IMPORTANT] 压缩操作不适用于链接（外部）图像，或嵌入的 SVG 和 GIF。

此操作默认未启用。

要压缩图像，请激活该图像的格式化器并点击“压缩图像”按钮：
compress button

该按钮仅对符合条件的图像类型可见。

所有压缩后的图像均为 jpeg 格式。

如果满足以下条件，则图像被视为“可压缩”：

其大小大于选项中的 maxWidth 值（如果有 - 见下文选项）。
图像已被调整大小，且其 width 属性小于其原始宽度。此条件仅在以绝对单位（px、rem 或 em）调整大小时才会满足。

使用相对单位（%）调整大小的图像，仅当其大于 maxWidth 值时才会被压缩。

在压缩前，会使用模态框来确认操作。模态框的样式和文本内容可在选项中完全自定义。模态框包含一个默认提示和一个“更多信息”按钮，用于展开更详细的说明。这些均可在选项中进行配置。将“更多信息”文本设置为 null 以隐藏该按钮。

完成后，会在格式化器覆盖层中显示一个反馈框，以显示减少的 kB 数量，以及图像的初始和最终尺寸。如果图像不可压缩（已为最佳大小），则显示此反馈框而非模态框。

选项

image: {
  allowCompressor: Boolean;
  compressorOptions: {
    jpegQuality: number;
    maxWidth?: number | null; 
    styles? : {
      modalBackground?: { [key: string]: any } | null | undefined;
      modalContainer?: { [key: string]: any } | null | undefined;
      buttonContainer?: { [key: string]: any } | null | undefined;
      buttons?: { [key: string]: any } | null | undefined;
    } | null | undefined;
    text: {
      prompt: string;
      moreInfo: string | null;
      reducedLabel: string; 
      nothingToDo: string;
    };
    icons: {
      continue: string;
      moreInfo: string;
      cancel: string;
    };
  }
}

allowCompressor: 启用 Compressor Action（默认值为 false）。
jpegQuality: 在缩小图像时应用的 jpeg 质量（压缩因子）。必须为 0 - 1，其中 0 表示绝对压缩（最低质量），1 表示不压缩（最高质量）。默认值为 0.8。此值通常会将文件大小减小到原始大小的 30%，而不会造成图像质量的明显下降。
maxWidth: 如果设置，当图像没有 width 属性，或使用相对（%）单位调整大小，且大于 maxWidth 值时，将图像缩小到此大小。默认值为 null。
styles: 上述指定的任何样式都将与默认样式合并，除非指定为 null，在这种情况下，渲染的模态框中将不包含 style 属性。您还可以指定 styles: null 以移除模态框中的所有内联样式。如果您更喜欢使用 CSS 来设置模态框的样式，可以在选择器中使用 div[data-blot-formatter-compress-modal] 来定位渲染的模态框元素。
text: 模态框和反馈框的文本或富文本 HTML
- prompt - 模态框打开时的文本
- moreInfo - 用户点击 ? 按钮时的额外详细信息。将此设置为 null 会隐藏 ? 按钮。
- reducedLabel - 文件大小缩减反馈的标签（上方截图中的 "Reduced"）。
- nothingToDo - 当没有压缩任务时，在反馈框中显示的文本。
icons - 指定按钮的 svg 字符串表示（不包含 width/height 属性）或其他合适的内部 HTML。

链接操作

:warning: 自 2.4 版本起新增

此操作管理图像 blot 上的超链接。它旨在方便直接在图像上放置链接，对于应用了浮动样式的图像尤其有用。

链接按钮默认启用。若要隐藏链接按钮，请将 allowLinkEdit 设置为 false（参见下文选项）。

blot formatter link action

如果图片包含链接，按钮将显示为激活状态。
点击链接按钮以显示表单。如果已设置，将显示当前值。
清除输入内容或点击垃圾桶图标以移除链接。

[!IMPORTANT] 如果链接跨越图片，在 BlotFormatter 中编辑该链接可能会导致意外结果，包括移除图片之后的链接，并保留图片之前的原始链接。只有图片本身会采用新值。对于跨越链接，请关闭覆盖层，并使用内置的 Quill 链接编辑器。

选项

与其他模态框一样，样式可通过选项完全自定义，既可以设置样式，也可以使用 css 类。

image: {
  allowLinkEdit: Boolean; // show link button for adding/editing links
  modal: {
    dialog: {
      className: string; // class name applied to the link modal dialog
      style?: { [key: string]: any } | null | undefined; // style applied to the modal dialog, or null to prevent styles
    };
    background: {
      className: string; // class name for screen background mask
      style?: { [key: string]: any } | null | undefined; // style for screen background mask
    };
    form: {
      className: string; // class name applied to the form element
      style?: { [key: string]: any } | null | undefined; // style applied to the form, or null to prevent styles
    };
    label: {
      className: string; // class name applied to the label element
      style?: { [key: string]: any } | null | undefined; // style applied to the label, or null to prevent styles
      text: string; // text content for the label element
    };
    input: {
      className: string; // class name applied to the input element
      style?: { [key: string]: any } | null | undefined; // style applied to the input, or null to prevent styles
      placeholder?: string | null | undefined; // placeholder text for the input
    };
    buttons: {
      submit: {
        className: string; // class name applied to the submit button
        style?: { [key: string]: any } | null | undefined; // style applied to the submit button, or null to prevent styles
        icon: string; // inner html for submit button (svg recommended)
        tooltip: string; // tooltip text for submit button
      },
      cancel: {
        className: string; // class name applied to the cancel button
        style?: { [key: string]: any } | null | undefined; // style applied to the cancel button, or null to prevent styles
        icon: string; // inner html for cancel button (svg recommended)
        tooltip: string; // tooltip text for cancel button
      },
      remove: {
        className: string; // class name applied to the remove button
        style?: { [key: string]: any } | null | undefined; // style applied to the remove button, or null to prevent styles
        icon: string; // inner html for remove button (svg recommended)
        tooltip: string; // tooltip text for remove button
      }
    }
  }
}

光标操作

:warning: 2.4 版本新增

此操作会为左右方向键添加监听器，以停用 blot 格式化器覆盖层，并将光标放置在图像之前或之后。对右方向键的响应依赖于浏览器 API 来正确定位光标，因为 Quill 的原生方法会错误地将光标定位在格式化 span 包装器内部。如果任何 blot 格式化器模态框处于打开状态，该操作将被禁用。

此操作没有选项。

包含的自定义 Blots

此包包含两个自定义 blots，分别对应 Image 和 Video，它们覆盖了同名的 Quill blot 类型。

:warning: 这两个 blot 默认均未注册。要将这些 blots 注册到 Quill，请使用以下选项：

blotFormatter2: {
  image: {
    registerImageTitleBlot: true,
  },
  video: {
    registerCustomVideoBlot: true,
  }
}

图像

这是一个修改过的 Image blot（source），它为默认的 Quill Image blot 添加了 title 属性支持。如果你使用 Attribute 操作来编辑 alt/title，则必须使用此 blot 或使用 title 支持注册你自己的 blot。

此 blot 不会移除空的 alt 属性。这是为了无障碍兼容性，并允许编辑器设置一个空白的 alt 以告知屏幕阅读器忽略该图像。

用于创建类对象的工厂方法作为 createAltTitleImageBlotClass 导出。

用法

const ImageAltTitleBlot = createAltTitleImageBlotClass(Quill);
Quill.register({ 'formats/image': ImageAltTitleBlot }, true);

如果你使用 registerImageTitleBlot 选项，则通过 BlotFormatter2 完成此操作。

视频

这是一个修改过的 Video blot（source），它会添加宽高比为 16:9（YouTube 的默认值）且初始宽度为 100% 的视频，而不是默认的 350x150px。

如果你想使用具有不同宽高比的自定义 blot，可以通过 defaultAspectRatio 设置来配置。例如，要设置为 2:1：

video: {
  registerCustomVideoBlot: true,
  defaultAspectRatio: '2/1 auto'
}

此补丁还修复了 Quill 的一个 bug，即在使用 quill.getSemanticHTML() 时，视频嵌入会被输出为超链接。使用此自定义 blot，iframe 将完全按照编辑器中的原样进行复制。

一个用于创建类对象的工厂方法被导出为 createResponsiveVideoBlotClass。

用法

const VideoResponsive = createResponsiveVideoBlotClass(Quill);
Quill.register({ 'formats/video': VideoResponsive }, true);

如果您使用 registerCustomVideoBlot 选项，则通过 BlotFormatter2 实现。

格式化图像

:warning: 2.2 版本新增

调整大小后的图像始终会将 height 属性设置为 auto。原始的 blot-formatter 包设置了一个固定的像素高度，如果 width 超过了该图像的 max-width 样式，则会导致失真。如果从之前的版本升级到 2.2，您需要调整图像大小以获得此修复。

选项

  image: {
    allowAltTitleEdit: true,
    registerImageTitleBlot: false,
    registerArrowRightFix: true
  },

allowAltTitleEdit: boolean：在覆盖层上显示 alt/title T 按钮（参见上一节）
registerImageTitleBlot: boolean：注册支持 title 属性 delta 的自定义 Image blot（参见上一节）
registerArrowRightFix: boolean：注册一个键盘绑定，以修复 Quill 的一个 bug，该 bug 导致当使用右箭头将光标移动到图像的 span 标签时，光标会消失。

格式化视频

:warning: 2.2 版本新增

现在支持为 iframe 设置自定义宽高比。

每个 iframe 现在都会获得一个唯一的代理图像，以兼容触摸屏。为了兼容可滚动编辑器，代理图像现在存在于 Quill 容器中，而不是文档 body 的末尾。

:warning: 如果你使用可滚动编辑器，请确保将容器的 overflow 设置为 hidden。有关更多信息，请参阅下文中的 Scrollable Editors。

当向编辑器内容中添加视频时，blot-formatter-2 会为其分配一个透明的“proxy-image”遮罩，以防止与 iframe 内容交互。点击此代理图像将激活该视频的格式化覆盖层。

在以下任一情况发生时，代理图像的位置都会得到保持：Quill 的 text-change 事件触发、窗口或编辑器被滚动、编辑器被调整大小（包括移动设备屏幕方向改变）。

[!IMPORTANT] 建议你在 iframe 上设置 aspect-ratio 样式，可以通过内联样式或 css 实现。这对于 iframe 的相对尺寸设置至关重要。

选项

  video: {
    selector: 'iframe.ql-video',
    registerCustomVideoBlot: false,
    registerBackspaceFix: true,
    defaultAspectRatio: '16/9 auto',
    proxyStyle: {}
  }

selector: string: 用于确定哪些元素是 iframe，以便为其分配代理图像。如果您使用未包含 Quill 默认 ql-video 类的自定义视频 blot，请根据您的需求修改此项。
- defaultAspectRatio: string: 设置已注册的自定义视频 blot 所使用的宽高比。如果未通过内联样式或 CSS 定义宽高比，且尺寸模式为相对模式，则在调整大小时将使用此值。请注意，在这种情况下，此值不是粘性的，也不会保存到 Quill delta 中。
- registerCustomVideoBlot: boolean: 注册一个自定义视频 blot，其宽高比由 defaultAspectRatio 指定，默认为 aspect-ratio: 16 / 9 auto;（YouTube 默认值），初始宽度为 100%（见下文）。
- registerBackspaceFix: boolean: 注册一个退格键绑定，用于修复以下 Quill bug: 如果存在两个相邻的视频 blot，且第一个通过退格键删除，则已删除 blot 的尺寸属性会被传递给剩余的 blot。
- proxyStyle: { [key: string]: any } | null | undefined: 一个可选的映射类型样式设置，用于添加到代理图像。对于排查与代理定位相关的任何问题，使用 {'border': '5px red solid'} 来可视化代理放置位置可能很有用。

CSS

建议的 css 可在 src/css/quill-blot-formatter2.css 中找到（如下所示）。这也导出到 dist 文件夹并通过 npm 发布：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@enzedonline/quill-blot-formatter2/dist/css/quill-blot-formatter2.css">

这些样式不会自动加载，由您负责加载与您的站点相关的样式。

建议的 CSS

可通过 CDN 或 import 获取，如果您的环境支持此功能。

div.ql-editor {
    --blot-align-left-margin: 0.5rem 1rem 0.5rem 0;
    --blot-align-center-margin: 1rem auto;
    --blot-align-right-margin: 0.5rem 0 0.5rem 1rem;
}

/* image wrapper common */
div.ql-editor [class^="ql-image-align-"] {
    display: flex;
    flex-wrap: wrap;
    width: var(--resize-width);
    max-width: 100%;
}
div.ql-editor [class^="ql-image-align-"]>img {
    flex: 1 1 auto;
    z-index: 1; /* prevents clipping by neighbouring text margin in some cases */
}
/* left */
div.ql-editor .ql-image-align-left,
div.ql-editor .ql-iframe-align-left {
    margin: var(--blot-align-left-margin);
    float: left;
}
/* centre */
div.ql-editor .ql-image-align-center,
div.ql-editor .ql-iframe-align-center {
    margin: var(--blot-align-center-margin);
}
/* right */
div.ql-editor .ql-image-align-right,
div.ql-editor .ql-iframe-align-right {
    margin: var(--blot-align-right-margin);
    float: right;
}

/* image caption */
/* common */
div.ql-editor [class^="ql-image-align-"][data-title] {
    margin-bottom: 0;
}
div.ql-editor [class^="ql-image-align-"][data-title]::after {
    content: attr(data-title);
    padding: 0.25rem 0.2rem;
    font-size: 0.9rem;
    line-height: 1.1;
    background-color: white;
    width: 100%;
}
/* remove text decoration on caption when image linked */
a:has([class^="ql-image-align-"]>img) {
    text-decoration: none !important;
}
/* left */
div.ql-editor .ql-image-align-left[data-title]::after {
    text-align: left;
}
/* center */
div.ql-editor .ql-image-align-center[data-title]::after {
    text-align: center;
}
/* right */
div.ql-editor .ql-image-align-right[data-title]::after {
    text-align: right;
}

:warning: 2.2 新增

--resize-width 样式属性在 2.2 版本中引入，它是目标元素 width 属性的副本。在 span 包装器上设置此值的 width 允许使用 flex 显示，并采用更简洁的样式，包括不再使用包裹的图片说明来裁剪图像。如果您正在从以前的版本升级此包，在将 blot 加载到编辑器之前，该属性将不存在。

如果您有来自以前版本的内容，并希望利用此样式而无需更新内容中的每个对齐图像，您可以使用以下内容来允许两种格式共存：

2.2 版本还引入了 data-relative 属性，作为使用混合绝对和相对大小的站点的 css 辅助工具。它被添加到每个格式化图像中，但不存在于以前版本中对齐的 blot 上。要将以前的样式应用于 2.2 之前的内容，请在您以前的 css 定义中的每个对齐选择器中添加 :not[data-relative]，并在上述每个对齐选择器中添加 [data-relative]。

例如：
/* pre-2.2 styling */
div.ql-editor .ql-image-align-center:not[data-relative],
div.ql-editor .ql-iframe-align-center:not[data-relative] {
  margin: 0.5rem auto;
  display: block;
}
/* post 2.2 styling */
div.ql-editor .ql-image-align-center[data-relative],
div.ql-editor .ql-iframe-align-center[data-relative] {
   margin: var(--blot-align-center-margin);
}

模态框

如果您在具有提升的 z-index 的模态表单中使用 Quill，您可能需要增加 z-index 以便代理正确覆盖 iframe。这可以通过在 Options 中使用 video.proxyStyle 设置来完成。例如：

  video: {
    proxyStyle: {
      zIndex: 10
    }
  }

或者，使用 css 修改 img.blot-formatter__proxy-image 的样式。

img.blot-formatter__proxy-image {
  z-index: 10; /* use an appropriate value here */
}

请注意，代理图像的 z-index 不要高于 Quill 工具栏，因为这可能导致代理覆盖工具栏按钮。

[!IMPORTANT] 另请参阅下方关于可滚动 Quill 编辑器的说明，如果您的编辑器可滚动或具有 max-height 属性。

响应式网站的条件样式

响应式设计师面临的一个难题是，当元素可以是任意宽度时，在考虑较小屏幕尺寸时如何以合理的方式处理这种情况。例如，您可以将所有图像在 600px 以下的屏幕上设置为 100%，但这将把所有图像视为相等，无论它们是 20px 还是 2000px（或 10% 还是 75%）。在这种情况下，如果您有一个宽度为 20% 且断点为 600px 的图像，当屏幕尺寸缩小到该阈值以下时，您的图像将从 120px 突然跳转到 600px。

可以使用 --resize-width 样式属性来逐步增加对齐图像的宽度，最大值为 100%。

以下示例 CSS 在屏幕尺寸从 900px 减小到 500px 的过程中，每减少 100px，将相对尺寸的图像逐步扩展 20%，最大值为 100%。

      div.ql-editor [class^="ql-image-align-"] {
        width: var(--resize-width);
        max-width: 100%;
      }
      @media (max-width: 900px) {
        div.ql-editor [class^="ql-image-align-"][data-relative="true"] {
          width: calc(var(--resize-width) + 20%);
        }
      }
      @media (max-width: 800px) {
        div.ql-editor [class^="ql-image-align-"][data-relative="true"] {
          width: calc(var(--resize-width) + 40%);
        }
      }
      @media (max-width: 700px) {
        div.ql-editor [class^="ql-image-align-"][data-relative="true"] {
          width: calc(var(--resize-width) + 60%);
        }
      }
      @media (max-width: 600px) {
        div.ql-editor [class^="ql-image-align-"][data-relative="true"] {
          width: calc(var(--resize-width) + 80%);
        }
      }
      @media (max-width: 500px) {
        div.ql-editor [class^="ql-image-align-"][data-relative="true"] {
          width: 100%;
        }
      }

[!Note] 这种方法略显简单，如果将其应用于浮动图片或表格，且 calc 语句的结果值（例如）介于 80% 和 100% 之间，可能会导致相邻内容被“挤压消失”。一种更稳健（但更复杂）的方法使用 min/max 计算来模拟逻辑门（即模拟 if/else 子句），并根据 --resize-width 所在的范围将宽度步骤设置为固定宽度。该方法的描述可在这篇文章中找到。

[!IMPORTANT] 建议仅在编辑器外部（或当编辑器设置为只读时）应用这些响应式样式，否则这将干扰在这些屏幕尺寸下调整 blot 大小的能力。

Quill Bug Fixes

BlotFormatter 提供了两个 Quill 错误修复。

registerArrowRightFix

注册一个键盘绑定，修复 Quill 的一个错误：当使用右箭头将光标移动到图片的 span 标签时，光标会消失。

默认启用，在选项中禁用：

  image: {
    registerArrowRightFix: false
  },

containTooltipPosition

:warning: 3.0 版本新增

防止 Quill 将 tooltip 元素渲染到 Quill 容器之外。这对于可滚动的 Quill 编辑器特别有用，其中 quill.container 方法具有 overflow: hidden 或 overflow: clip。如果 Quill 尝试将 tooltip 放置在容器边界之外，此修复将使其放置在内部并保留一个小边距。
此修复旨在用于可滚动的 Quill 容器。

无 tooltip 修复

有 tooltip 修复

默认禁用。在选项中启用：

  tooltip: {
    containTooltipPosition: true
  }

[!NOTE] 此修复也可通过具有静态方法的导出类使用。两种方法都接受 quill 实例。您还可以添加 true 作为额外参数，以在调试控制台中获取详细反馈。
TooltipContainPosition.watchTooltip(quill); // start watching changes to the tooltip element, reposition if necessary
TooltipContainPosition.removeTooltipWatcher(quill); // stop watching changes to the tooltip element

可滚动编辑器

[!IMPORTANT] 许多与可滚动编辑器相关的现有 bug 已在 2.2 版本中修复。如果您使用旧版本且使用可滚动的 Quill 编辑器，建议升级到该版本。请参阅 Change Log 以获取更多详细信息。

Quill Blot Formatter 2 已针对可滚动编辑器元素（quill.root）进行了测试。不建议用于可滚动容器（quill.container）。

如果您的 Quill 根元素可滚动，任何活动覆盖层都会随目标元素一起滚动。然而，覆盖层元素和代理图像位于 Quill 容器元素中，并且会在编辑器边界之外可见。代理图像可能会滚动出可用窗口，导致其溢出，同时可能遮挡编辑器外部的元素。

基于这些原因，您必须将 Quill 容器的 overflow 设置为 clip 或 hidden。我建议在这样做时使用 containTooltipPosition Quill 修复，以避免 Quill 在裁剪/隐藏区域中渲染 tooltip 元素。

例如：

.ql-editor {
  max-height: 25rem;
  overflow-y: auto;
}
.ql-container {
  overflow: hidden;
}

:warning: 2.2 版本新增。

在之前的版本中，工具栏设置是 align 设置的子属性。

当覆盖层激活时，格式化器会加载目标 blot 的已启用（且相关）操作。每个操作都有一个可选的 ToolbarButtons 数组，这些会被加载到覆盖层工具栏中。这些操作在每次显示和隐藏覆盖层时创建和销毁。当操作被启用或禁用时，其相关的工具栏按钮会在工具栏上显示/隐藏。

Options

工具栏选项涉及样式和图标定义，在大多数情况下不应需要修改：

toolbar: {
  // toolbar icons - key name must match toolbar name & alignment name if relevant 
  icons: Record<string, string>,
  // class name applied to the root toolbar element
  mainClassName: string,
  // style applied to root toolbar element, or null to prevent styles
  mainStyle?: { [key: string]: any } | null | undefined,
   // style applied to buttons, or null to prevent styles
  buttonStyle?: { [key: string]: any } | null | undefined,
  // class name applied to each button in the toolbar
  buttonClassName: string,
  // style applied to the svgs in the buttons
  svgStyle?: { [key: string]: any } | null | undefined,
}

有关配置和扩展工具栏及按钮的更多信息，请参阅下方的开发者说明。

配置选项

请参阅上文相关章节，以获取可用选项的更详细说明。此外，Options 模块在每个类型定义中都有内联说明。

对于使用 blot-formatter-2 的自定义 Image 和 Video blots 的设置，启用 alt/title 编辑和可选的相对尺寸（相对尺寸为默认值）：

blotFormatter2: {
  image: {
    registerImageTitleBlot: true
  },
  video: {
    registerCustomVideoBlot: true,
  },
  resize: {
    useRelativeSize: true,
    allowResizeModeChange: true,
  },
  image: {
    allowAltTitleEdit: true
  }
},

使用 quill 模块选项，可以轻松禁用现有的 specs、actions，或覆盖此模块提供的任何样式。

例如：如果您想禁用调整大小、仅支持图片、禁用 alt/title 编辑，并更改 overlay 边框，以下配置将有效：

import Quill from 'quill';

// from main module
import BlotFormatter2, { ImageSpec } from 'quill-blot-formatter2'

Quill.register('modules/blotFormatter2', BlotFormatter2);

const quill = new Quill(..., {
  modules: {
    ...
    blotFormatter2: {
      image: {
        allowAltTitleEdit: false
      }
      specs: [
        ImageSpec,
      ],
      overlay: {
        style: {
          border: '2px solid red',
        }
      },
      resize: {
        allowResizing: false
      }    
    }
  }
});

要启用带有调试控制台日志记录的详细模式，请设置以下选项：

blotFormatter2: {
  debug: true;
}

[!TIP] 有关所有支持的选项，请参阅 Options.
有关默认选项值，请参阅 DefaultOptions.
对象属性会被合并，但数组属性会覆盖默认值。
要完全禁用样式（overlay.style、resize.handleStyle 等），请将它们设置为 null。

进一步自定义

[!NOTE] 从这里的说明仅面向希望自定义默认行为和/或使用自定义 blot 的用户。

blotFormatter2 已经兼容 Quill Image 和 Video blot，无需注册任何自定义 blot 或操作即可与此包配合使用，但您需要使用包含的自定义 Image blot（或使用 title 支持创建自己的）来使用 alt/title 编辑功能。

[!IMPORTANT] 如果您创建任何可能以某种方式移动或更改内容的自定义操作，建议调用 formatter.update()，其中 formatter 是 BlotFormatter 的当前实例。这确保了覆盖层和代理的位置和大小得以保持。

无论如何，代理位置都会在 Quill 的 text_change 事件上更新。对于其他 Quill 扩展，它们在插入/更改内容时应触发 text_change 事件。

如果您正在 fork 此项目，请使用 npm run build 输出 UMD 和 ESM 构建，使用 use npm run dev 启动 Vite 服务器，在默认页面和用于测试构建的附加页面上进行实时更改。

BlotSpec

BlotSpec（/src/specs/BlotSpec.ts）类定义了 BlotFormatter 如何与 blot 交互。它们将 BlotFormatter 作为构造函数参数，并具有以下属性和函数：

`isUnclickable: boolean`

如果此 blot 类型将具有代理图像掩码，则设置为 true。默认情况下为 false。

`init(): void`

在所有 spec 构建完成后调用。使用此方法绑定到 quill 事件，以确定何时激活特定的 spec。

`getActions(): Array<Action>`

此 blot 上允许的 actions。默认为 [AlignAction, ResizeAction, DeleteAction]，对于图像 blot 则额外添加 AttributeAction。

`getTargetElement(): HTMLElement | null`

当 spec 处于激活状态时，此处应返回要格式化的元素

`getOverlayElement(): HTMLElement | null`

当 spec 处于激活状态时，此处应返回用于显示格式化覆盖层的元素。由于它们通常是同一个元素，因此默认为 return getTargetElement()。

`setSelection(): void`

在 spec 激活后，此处应使用 setSelection 设置 quill 选区。默认为 quill.setSelection(null)。

`onHide(): void`

当用户点击 blot 外部导致 spec 被取消激活时调用。使用此方法清理 spec 在激活期间的任何状态。

Notes

每个 spec 都应调用 this.formatter.show(this); 以请求激活。请参阅 specs/（/src/specs）了解内置的 spec。

Action

Action（/src/actions/Action.ts）类定义了 blot 的 spec 激活后可用的操作。它们以 BlotFormatter 作为构造函数参数，并具有以下属性和函数：

`toolbarButtons: ToolbarButton[]`

ToolbarButtons 的可选数组，每当格式化器显示且此操作处于激活状态时，会被添加到覆盖层工具栏中。

`onCreate(): void`

在操作创建后立即调用。使用此方法绑定 quill 事件并创建需要附加到覆盖层的任何元素。

`onUpdate(): void`

当格式化器更改了 blot 上的某些内容时调用。使用此方法更新任何内部状态。

`onDestroy(): void`

当用户隐藏格式化器时调用。

请参阅 actions（/src/actions）了解现有的操作。

[!IMPORTANT] 如果你创建了一个需要模态框的自定义操作，请在其中一个模态框元素上包含数据集属性 blotFormatterModal，并将该模态框作为 overlay 的子元素添加。这将禁用你的模态框上的 Blot Formatter 键盘监听器和上下文菜单拦截器。例如：
dialog.dataset.blotFormatterModal = '';

:warning: 2.2 版本新增

负责创建格式化器 overlay 工具栏，并根据已加载的操作添加按钮。

工具栏以当前的格式化器实例作为参数：formatter: BlotFormatter

工具栏有两个方法：

`create(): void`

由 formatter.show 调用。创建用于所选 blot 的工具栏按钮。

遍历 formatter.createActions(spec) 中加载的所有操作，并为 action.ToolbarButtons. 中定义的每个按钮创建一个 ToolbarButton

`destroy(): void`

在调用 formatter.hide() 时，为 Toolbar 实例整理内容和资源。ToolbarButton.destroy() 会为每个已加载的 ToolbarButton 调用。

ToolbarButton

:warning: 2.2 版本新增

每当格式化器显示时，在操作创建之后，为每个已创建的操作定义的按钮会被加载到覆盖工具栏中。

每个 ToolbarButton 接受以下参数：

  action: string,
  onClickHandler: EventListener,
  options: ToolbarOptions

action 应与图标名称匹配，并且也会作为数据属性 data-action="name" 添加到按钮上。在单个操作对应多个按钮的情况下，可以使用此属性来确定哪个按钮被点击（参见 AlignAction 作为示例）。

onClickHandler 应是一个箭头函数，当按钮创建时，它将被添加为 onClick 事件监听器。在此处使用箭头函数以确保处理函数绑定到正确的类实例。

options 是 formatter.options.toolbar 实例。

一个基本示例是 AttributeAction 按钮：

export default class AttributeAction extends Action {

    constructor(formatter: BlotFormatter) {
        super(formatter);
        if (formatter.options.image.allowAltTitleEdit) {
            this.toolbarButtons = [
                new ToolbarButton(
                    'attribute',
                    this.onClickHandler,
                    this.formatter.options.toolbar,
                )
            ]
        }
    }

    onClickHandler: EventListener = () => {
        this.showAltTitleModal();
    }
    ....

ToolbarButton 具有以下方法：

`create(visible: string | boolean = true): HTMLElement`

创建一个工具栏按钮实例，包括 HTML 元素，添加 onClick 事件监听器，并确定按钮在加载时是否应被选中。

formatter.show() 将通过 Toolbar.create() 为每个已加载的 action 的 toolbarButtons 属性中列出的每个按钮调用此方法。

`destroy(): void`

清理工具栏按钮的所有属性。由 formatter.hide() 通过 Toolbar.destroy() 调用。

`preselect(): boolean`

根据条件返回 true/false，以确定在加载时是否应选中该按钮。由 create() 调用。一个基本示例是 ResizeAction 中的调整大小模式按钮，如果目标 blot 使用相对单位（%）进行大小设置，则预选中该按钮。

preselect = () => {
  return this.isRelative;
}

`selected(): boolean`

获取按钮当前选中的状态。

`selected(value: boolean)`

设置按钮当前选中状态的 Setter，例如 button.selected = true。

`visible(): boolean`

获取按钮的可见状态（若为 style.display !== 'none' 则为 true）

`visible(style: string | boolean)`

设置按钮可见状态的 Setter（display = 'inline-block' 如果 true 否则 display = 'none'），例如 button.visible = false

Quill Blot Formatter 2 (quill-blot-formatter2)

目录

新功能

版本 3.2

版本 3.1

版本 3.0

Version 2.4

Version 2.3

Version 2.2

Version 2.2.2

Version 2.1

安装

使用示例

Node.js / CommonJS

ESM（React、Next.js、Angular、Vue、Vite 等）

Angular

React / Next.js

在 <script type="module"> 中使用 ESM（浏览器）

在 <script> 标签中使用 UMD（浏览器）

在 Quill 中注册 Blotformatter

使用建议的对齐格式样式

通过导入（React 等）

通过 CDN

与 formats 配置配合使用

演示

操作

对齐操作

Options

Resize Action

尺寸信息显示

选项

Using Relative Sizes

使用 allowResizeModeChange = false：

使用 allowResizeModeChange = true：

在触摸屏上调整大小 :warning:2.2 版本新增

删除操作

选项

属性操作（仅限图像 blot）

Options

Styles

Icons

Labels

使用标题作为说明文字

压缩操作（仅限嵌入式图像斑点）

选项

链接操作

选项

光标操作

包含的自定义 Blots

图像

视频

格式化图像

选项

格式化视频

选项

CSS

建议的 CSS

模态框

响应式网站的条件样式

Quill Bug Fixes

registerArrowRightFix

containTooltipPosition

可滚动编辑器

Formatter Toolbar

Options

配置选项

进一步自定义

BlotSpec

isUnclickable: boolean

init(): void

getActions(): Array<Action>

getTargetElement(): HTMLElement | null

getOverlayElement(): HTMLElement | null

setSelection(): void

onHide(): void

Notes

Action

toolbarButtons: ToolbarButton[]

onCreate(): void

onUpdate(): void

在 `<script type="module">` 中使用 ESM（浏览器）

在 `<script>` 标签中使用 UMD（浏览器）

使用 `allowResizeModeChange = false`：

使用 `allowResizeModeChange = true`：

`isUnclickable: boolean`

`init(): void`

`getActions(): Array<Action>`

`getTargetElement(): HTMLElement | null`

`getOverlayElement(): HTMLElement | null`

`setSelection(): void`

`onHide(): void`

`toolbarButtons: ToolbarButton[]`

`onCreate(): void`

`onUpdate(): void`

`onDestroy(): void`

`create(): void`

`destroy(): void`

`create(visible: string | boolean = true): HTMLElement`

`destroy(): void`

`preselect(): boolean`

`selected(): boolean`

`selected(value: boolean)`

`visible(): boolean`

`visible(style: string | boolean)`