工具栏模块

Toolbar 模块允许用户轻松格式化 Quill 的内容。

¥The Toolbar module allow users to easily format Quill's contents.

它可以配置自定义容器和处理程序。

¥It can be configured with a custom container and handlers.

const quill = new Quill('#editor', {
  modules: {
    toolbar: {
      container: '#toolbar', // Selector for toolbar container
      handlers: {
        bold: customBoldHandler
      }
    }
  }
});

由于 container 选项非常常见，因此也允许使用顶层简写。

¥Because the container option is so common, a top level shorthand is also allowed.

const quill = new Quill('#editor', {
  modules: {
    // Equivalent to { toolbar: { container: '#toolbar' }}
    toolbar: '#toolbar'
  }
});

容器

¥Container

工具栏控件可以通过简单的格式名称数组或自定义 HTML 容器来指定。

¥Toolbar controls can either be specified by a simple array of format names or a custom HTML container.

首先使用更简单的数组选项：

¥To begin with the simpler array option:

const toolbarOptions = ['bold', 'italic', 'underline', 'strike'];

const quill = new Quill('#editor', {
  modules: {
    toolbar: toolbarOptions
  }
});

控件也可以通过嵌套数组的一级进行分组。这将把控件封装在类名为 ql-formats 的 <span> 中，为主题提供可用的结构。例如，雪花 在控件组之间添加了额外的间距。

¥Controls can also be grouped by one level of nesting an array. This will wrap controls in a <span> with class name ql-formats, providing structure for themes to utilize. For example Snow adds extra spacing between control groups.

const toolbarOptions = [['bold', 'italic'], ['link', 'image']];

可以使用以格式名称作为唯一键的对象来指定具有自定义值的按钮。

¥Buttons with custom values can be specified with an Object with the name of the format as its only key.

const toolbarOptions = [{ header: '3' }];

下拉菜单类似地由一个对象指定，但使用一个可能值的数组。CSS 用于控制下拉选项的可视化标签。

¥Dropdowns are similarly specified by an Object, but with an array of possible values. CSS is used to control the visual labels for dropdown options.

// Note false, not 'normal', is the correct value
// quill.format('size', false) removes the format,
// allowing default styling to work
const toolbarOptions = [
  { size: [ 'small', false, 'large', 'huge' ]}
];

注意：主题 还可以指定下拉菜单的默认值。例如，如果设置为空数组，雪花 会为 color 和 background 格式提供 35 种默认颜色列表。

¥Note Themes may also specify default values for dropdowns. For example, Snow provides a default list of 35 colors for the color and background formats, if set to an empty array.

const toolbarOptions = [
  ['bold', 'italic', 'underline', 'strike'],        // toggled buttons
  ['blockquote', 'code-block'],
  ['link', 'image', 'video', 'formula'],

  [{ 'header': 1 }, { 'header': 2 }],               // custom button values
  [{ 'list': 'ordered'}, { 'list': 'bullet' }, { 'list': 'check' }],
  [{ 'script': 'sub'}, { 'script': 'super' }],      // superscript/subscript
  [{ 'indent': '-1'}, { 'indent': '+1' }],          // outdent/indent
  [{ 'direction': 'rtl' }],                         // text direction

  [{ 'size': ['small', false, 'large', 'huge'] }],  // custom dropdown
  [{ 'header': [1, 2, 3, 4, 5, 6, false] }],

  [{ 'color': [] }, { 'background': [] }],          // dropdown with defaults from theme
  [{ 'font': [] }],
  [{ 'align': [] }],

  ['clean']                                         // remove formatting button
];

const quill = new Quill('#editor', {
  modules: {
    toolbar: toolbarOptions
  },
  theme: 'snow'
});

对于需要更多自定义的用例，你可以手动用 HTML 创建一个工具栏，并将 DOM 元素或选择器传递给 Quill。ql-toolbar 类将被添加到工具栏容器中，Quill 会将相应的处理程序附加到 <button> 和 <select> 元素，类名格式为 ql-${format}。Buttons 元素可以选择具有自定义 value 属性。

¥For use cases requiring even more customization, you can manually create a toolbar in HTML, and pass the DOM element or selector into Quill. The ql-toolbar class will be added to the toolbar container and Quill attach appropriate handlers to <button> and <select> elements with a class name in the form ql-${format}. Buttons element may optionally have a custom value attribute.

<!-- Create toolbar container -->
<div id="toolbar">
  <!-- Add font size dropdown -->
  <select class="ql-size">
    <option value="small"></option>
    <!-- Note a missing, thus falsy value, is used to reset to default -->
    <option selected></option>
    <option value="large"></option>
    <option value="huge"></option>
  </select>
  <!-- Add a bold button -->
  <button class="ql-bold"></button>
  <!-- Add subscript and superscript buttons -->
  <button class="ql-script" value="sub"></button>
  <button class="ql-script" value="super"></button>
</div>
<div id="editor"></div>

<!-- Initialize editor with toolbar -->
<script>
  const quill = new Quill('#editor', {
    modules: {
      toolbar: '#toolbar'
    }
  });
</script>

注意：通过提供你自己的 HTML 元素，Quill 会搜索特定的输入元素，但你自己的与 Quill 无关的输入元素仍然可以添加、设置样式并共存。

¥Note by supplying your own HTML element, Quill searches for particular input elements, but your own inputs that have nothing to do with Quill can still be added and styled and coexist.

<div id="toolbar">
  <!-- Add buttons as you would before -->
  <button class="ql-bold"></button>
  <button class="ql-italic"></button>

  <!-- But you can also add your own -->
  <button id="custom-button"></button>
</div>
<div id="editor"></div>

<script>
  const quill = new Quill('#editor', {
    modules: {
      toolbar: '#toolbar',
    },
  });

  const customButton = document.querySelector('#custom-button');
  customButton.addEventListener('click', function () {
    console.log('Clicked!');
  });
</script>

处理程序

¥Handlers

工具栏控件默认应用并删除格式，但你也可以使用自定义处理程序覆盖此设置，例如，为了显示外部 UI。

¥The toolbar controls by default applies and removes formatting, but you can also overwrite this with custom handlers, for example in order to show external UI.

处理程序函数将绑定到工具栏（因此使用 this 将引用工具栏实例），如果相应的格式未启用，则传递输入框的 value 属性，否则传递 false 属性。添加自定义处理程序将覆盖默认的工具栏和主题行为。

¥Handler functions will be bound to the toolbar (so using this will refer to the toolbar instance) and passed the value attribute of the input if the corresponding format is inactive, and false otherwise. Adding a custom handler will overwrite the default toolbar and theme behavior.

const toolbarOptions = {
  handlers: {
    // handlers object will be merged with default handlers object
    link: function (value) {
      if (value) {
        const href = prompt('Enter the URL');
        this.quill.format('link', href);
      } else {
        this.quill.format('link', false);
      }
    }
  }
};

const quill = new Quill('#editor', {
  modules: {
    toolbar: toolbarOptions
  }
});

// Handlers can also be added post initialization
const toolbar = quill.getModule('toolbar');
toolbar.addHandler('image', showImageUI);