切换工具栏按钮

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

切换按钮在被点击时触发一个动作，并保持激活状态。这意味着它可以被切换为on或off。切换按钮通过CSS样式向用户提供其状态的视觉反馈。这种行为的一个例子是粗体按钮，当光标位于具有粗体格式的文本内时，该按钮会高亮显示。

选项

名称	值	要求	描述
text	string	可选	如果没有找到图标，则显示的文本。
icon	string	可选	要显示的图标的名称。必须对应于一个图标：在图标包中，在自定义图标包中，或者使用`addIcon` API添加。
tooltip	string	可选	按钮工具提示的文本。
enabled	boolean	可选	默认值：`true` - 表示按钮的启用状态。当为`false`时，按钮不可点击。可以通过按钮的API使用`setEnabled`进行更改。
active	boolean	可选	默认值：`false` - 表示按钮的激活状态。当为`true`时，按钮会高亮显示。可以通过按钮的API使用`setActive`进行更改。
onSetup	`(api) => (api) => void`	可选	默认值：`() => () => {}` - 在渲染按钮时调用的函数。有关详细信息，请参阅：使用`onSetup`。
onAction	`(api) => void`	必选	在按钮被点击时调用的函数。
shortcut	string	可选	要在工具提示中显示的快捷键。要注册快捷键，请参阅：向TinyMCE添加自定义快捷键。
context	string	可选	默认值：`mode:design` - context属性根据编辑器的当前状态动态启用或禁用按钮。有关详细信息，请参阅：上下文。

API

名称	值	描述
isEnabled	`() => boolean`	检查按钮是否已启用。
setEnabled	`(state: boolean) => void`	设置按钮的启用状态。
isActive	`() => boolean`	检查按钮是否处于激活（切换为开）状态。
setActive	`(state: boolean) => void`	设置按钮的激活（切换）状态。
setText	`(text: string) => void`	设置要显示的文本标签。
setIcon	`(icon: string) => void`	设置按钮的图标。

切换按钮示例和说明

HTML

<textarea id="custom-toolbar-toggle-button">
  <p><img style="display: block; margin-left: auto; margin-right: auto;" title="Tiny 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>发现错误？</h2>
  <p>如果您认为发现了错误，请在<a href="https://github.com/tinymce/tinymce/issues">GitHub仓库</a>上创建一个问题向开发人员报告。</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-toggle-button',
  toolbar: 'customStrikethrough customToggleStrikethrough',
  setup: (editor) => {
    editor.ui.registry.addToggleButton('customStrikethrough', {
      text: 'Strikethrough',
      onAction: (api) => {
        editor.execCommand('mceToggleFormat', false, 'strikethrough');
        api.setActive(!api.isActive());
      }
    });

    editor.ui.registry.addToggleButton('customToggleStrikethrough', {
      icon: 'strike-through',
      onAction: (_) => editor.execCommand('mceToggleFormat', false, 'strikethrough'),
      onSetup: (api) => {
        api.setActive(editor.formatter.match('strikethrough'));
        const changed = editor.formatter.formatChanged('strikethrough', (state) => api.setActive(state));
        return () => changed.unbind();
      }
    });
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});

上面的示例添加了两个自定义的删除线切换按钮。这两个按钮都使用mceToggleFormat命令来应用和移除删除线格式。该命令会切换指定的格式的开启和关闭状态，但仅对已注册到编辑器的格式有效。在这个示例中，strikethrough是已注册的格式。

基本切换：手动管理状态

第一个（customStrikethrough）按钮应用和移除删除线格式。其状态在点击时通过api.setActive(!api.isActive())进行切换。然而，这个按钮并不反映所选内容是否有删除线格式，这是它的预期行为。将光标移入有删除线格式的内容中不会激活该按钮，移出也不会取消激活它。

状态同步切换：自动更新状态

第二个按钮（customToggleStrikethrough）通过在onSetup回调中使用editor.formatter.formatChanged来解决这个问题，以监视当前选区的格式状态。

通过editor.execCommand(command, ui, args)传递给mceToggleFormat的格式名称与editor.formatter.formatChanged(formatName, callback)中使用的格式名称相同。

formatChanged方法接受以下参数：

formats（字符串，必填） — 要监视的已注册格式名称的逗号分隔列表。
callback（函数，必填） — 当格式状态改变时调用的函数。该回调函数接收一个state布尔值，指示当前选区中是否存在该格式（true表示存在，false表示不存在）。
similar（布尔值，可选） — 当设置为true时，将同一格式名称的所有相似变体视为等效，不考虑变量。默认值为false。
vars（对象，可选） — 限制监听器仅在应用的格式变量等于vars时匹配。

该方法返回一个包含unbind函数的对象。调用unbind()会移除格式监听器，这对于按钮销毁时的清理工作至关重要。

在示例中，onSetup首先使用editor.formatter.match('strikethrough')检查当前选区是否匹配删除线格式，并根据情况设置初始的活动状态。然后，它注册一个formatChanged监听器，每当删除线状态改变时，该监听器会调用api.setActive(state)。从onSetup返回的清理函数会调用changed.unbind()来清理监听器。

这种方法确保只要光标位于有删除线格式的内容中，customToggleStrikethrough就会被高亮显示，当光标不在其中时则会被取消激活，无论格式是如何应用的。

使用`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`