拆分工具栏按钮

最后更新：2026-11-04 10:10:15

拆分按钮包含一个基础按钮和一个菜单按钮，二者封装在一个工具栏项目中。点击菜单按钮部分会打开一个下拉列表。基础按钮部分和菜单项可以配置为在点击时触发不同的操作。

选项

名称	值	目标组件	要求	说明
text	string	主按钮	可选	未找到图标时显示的文本。
icon	string	主按钮	可选	要显示的图标名称。必须对应于图标包、自定义图标包中的图标，或使用`addIcon` API添加的图标。
tooltip	string	主按钮	可选	鼠标悬停在主按钮上时显示的文本。
chevronTooltip	string	箭头按钮	可选	鼠标悬停在箭头按钮上时显示的文本。如果未提供，则使用主按钮的tooltip生成，例如：`"{tooltip} 菜单"`。
onAction	`(api) => void`	主按钮	必需	点击基础按钮部分时调用的函数。
select	`(value: string) => boolean`	选项菜单项	可选	默认值：`false` - 打开菜单时对每个选项运行的函数，用于确定是否应将其高亮显示为活动状态。
columns	number 或 `'auto'`	下拉菜单	可选	默认值：`1` - 选项列表的列数。当设置为多列时，将仅显示每个项目的图标。
fetch	`(success: (menu) => void) => void`	下拉菜单	必需	应传递下拉菜单选项列表的回调函数。
onItemAction	`(api, value) => void`	选项菜单项	必需	点击下拉列表选项时调用的函数。`value`从选定的选项菜单项传递。
onSetup	`(api) => (api) => void`	所有	可选	默认值：`() => () => {}` - 渲染按钮时调用的函数。有关详细信息，请参阅：使用 `onSetup`。
context	string	所有	可选	默认值：`mode:design` - context 属性根据编辑器的当前状态动态启用或禁用按钮。有关详细信息，请参阅：Context。

API

名称	值	说明
isEnabled	`() => boolean`	检查按钮是否启用。
setEnabled	`(state: boolean) => void`	设置按钮的启用状态。
isActive	`() => boolean`	检查按钮的切换状态。
setActive	`(state: boolean) => void`	设置按钮的切换状态。
setText	`(text: string) => void`	设置要显示的文本标签。
setIcon	`(icon: string) => void`	设置按钮的图标。
setTooltip	`(tooltip: string) => void`	设置主按钮的tooltip。

拆分按钮示例和说明

以下示例设置了一个带有文本标签和静态下拉菜单的拆分按钮。

HTML

<textarea id="custom-toolbar-split-button">
  <p><img style="display: block; margin-left: auto; margin-right: auto;" title="小型 logo" src="https://www.tiny.cloud/docs/tinymce/latest/_images/logos/android-chrome-256x256.png" alt="TinyMCE logo" width="128" height="128"></p>
  <h2 style="text-align: center;">欢迎使用 TinyMCE 编辑器演示！</h2>
  <p>从上面的列表框中选择一个菜单项，它会在光标位置插入内容到编辑器中。</p>

  <h2>有问题或需要帮助？</h2>
  <ul>
    <li>我们的 <a href="https://www.tiny.cloud/docs/tinymce/8/">文档</a> 是学习如何配置 TinyMCE 的绝佳资源。</li>
    <li>有具体问题？试试在 Stack Overflow 上的 <a href="https://stackoverflow.com/questions/tagged/tinymce" target="_blank" rel="noopener"><code>tinymce</code> 标签。</a></li>
    <li>我们还作为 <a href="https://www.tiny.cloud/pricing">TinyMCE 高级计划</a> 的一部分提供企业级支持。</li>
  </ul>

  <h2>发现了一个 bug？</h2>
  <p>如果您认为发现了一个 bug，请在 <a href="https://github.com/tinymce/tinymce/issues">GitHub 仓库</a> 上创建一个 issue 向开发人员报告。</p>

  <h2>最后……</h2>
  <p>需要文件上传功能？考虑使用 <a href="https://www.tiny.cloud/docs/tinymce/latest/uploadcare/" target="_blank" rel="noopener noreferrer">Uploadcare</a> 和 TinyMCE 结合，以获得快速、现代的上传体验。</p>
  <p>感谢支持 TinyMCE！我们希望它能帮助您和您的用户创建出色的内容。
    <br>来自 TinyMCE 团队的诚挚问候。</p>
</textarea>

tinymce.init({
  selector: 'textarea#custom-toolbar-split-button',
  toolbar: 'myButton',
  menubar: false,
  setup: (editor) => {
    editor.ui.registry.addSplitButton('myButton', {
      text: 'My Button',
      icon: 'info',
      tooltip: 'Execute my action',
      chevronTooltip: 'My Button menu options',
      onAction: () => editor.insertContent('<p>You clicked the main button</p>'),
      onItemAction: (api, value) => editor.insertContent(value),
      fetch: (callback) => {
        const items = [
          {
            type: 'choiceitem',
            icon: 'notice',
            text: 'Menu item 1',
            value: '&nbsp;<em>You clicked menu item 1!</em>'
          },
          {
            type: 'choiceitem',
            icon: 'warning',
            text: 'Menu item 2',
            value: '&nbsp;<em>You clicked menu item 2!</em>'
          }
        ];
        callback(items);
      }
    });
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});

拆分按钮与基本按钮类似，它们都需要一个 onAction 回调函数。onAction 回调函数应接收按钮的 API 并且不返回任何内容。当点击基本按钮部分时调用它。在这个例子中，onAction 调用 editor.insertContent(value)，将给定的内容插入编辑器中。

当点击菜单项时调用 onItemAction。回调函数会接收拆分按钮的 API 和所选菜单项的值。不应返回任何内容。该示例调用 editor.insertContent(value) 将值插入编辑器内容中。

每当拆分按钮的下拉菜单打开时调用 fetch 函数。它是一个接受一个回调函数并向其传递一个要在按钮下拉菜单中渲染的菜单项数组的函数。这允许异步获取菜单项。

选择菜单项

选择菜单项是用于拆分工具栏按钮菜单项的一种特殊类型的菜单项。有关拆分按钮的信息，请参阅：拆分工具栏按钮。

选项

名称	值	要求	描述
value	任意	必需	当点击选择菜单项时传递给 `onItemAction` 的一个值。
text	字符串	可选	要显示的文本。
icon	字符串	可选	要显示的图标的名称。必须对应一个图标：在图标包中，在自定义图标包中，或使用 `addIcon` API添加。
enabled	布尔值	可选	默认值：`true` - 表示菜单项的状态。当为`false`时，菜单项不可点击。通过菜单项的 API 切换。
shortcut	字符串	可选	要在快捷键标签中显示的文本。要注册快捷键，请参阅：向 TinyMCE 添加自定义快捷键。

关于选择菜单项如何在拆分工具栏按钮中使用的示例，请参阅：拆分按钮示例和解释。

使用 `onSetup`

onSetup 接收一个函数，该函数会收到组件的 API。该函数应返回一个回调，此回调在传入组件的 API 后不返回任何内容。这是因为 onSetup 在组件渲染时运行，而 onSetup 返回的回调在组件销毁时执行。从 onSetup 返回的函数本质上是一个 onTeardown 处理程序，可用于解除事件和回调的绑定。

需要说明的是，在代码中 onSetup 可能如下所示：

onSetup: (api) => {
  // 组件创建时运行
  // 配置组件或绑定事件监听器

  return (api) => {
    // 组件销毁时运行
    // 解除事件监听器或清理资源
  };
};

要将回调函数绑定到编辑器事件，请使用 editor.on(eventName, callback)。要解除事件监听器的绑定，请使用 editor.off(eventName, callback)。任何事件监听器都应当在销毁回调中解除绑定。唯一不需要解除绑定的编辑器事件是 init，例如 editor.on('init', callback)。

传递给 editor.off() 的回调函数应与传递给 editor.on() 的函数相同。例如，如果在按钮创建时将 editorEventCallback 函数绑定到 NodeChange 事件，onSetup 应返回 (api) => editor.off('NodeChange', editorEventCallback)。
如果 onSetup 未注册任何事件监听器，或者仅监听 init 事件，onSetup 可以返回一个空函数，例如 return () => {};。

拆分工具栏按钮

选项

API

拆分按钮示例和说明

选择菜单项

选项

使用 onSetup

使用 `onSetup`