侧边栏

TinyMCE 允许开发人员创建侧边栏，并在编辑器中受限且易于访问的区域添加自定义 UI 组件。侧边栏旨在允许管理员和插件开发人员提供可供 TinyMCE 用户访问的附加工具。

此功能仅在 TinyMCE 以 经典（classic）模式运行时支持。在 内联（inline）模式下不支持。有关编辑模式差异的更多信息，请参阅 经典编辑模式。

编辑器侧边栏 API

侧边栏 API 允许开发人员以类似于添加按钮或菜单项的方式，在编辑器实例上添加侧边栏。开发人员可以使用 setup 回调在 tinymce.init 中直接添加侧边栏，也可以在插件内添加。

addSidebar 函数的语法如下： editor.ui.registry.addSidebar(name:String, spec:Object)

注册新侧边栏时，会同时创建一个同名的切换侧边栏打开和关闭的工具栏按钮。然后，通过将侧边栏名称添加到 toolbar 选项中，可将此按钮包含在工具栏内。

规范对象（Specification object）

tooltip

tooltip 指定悬停在侧边栏切换按钮上时显示的工具提示。

类型： String

icon

icon 指定侧边栏切换按钮的图标。图标应为 TinyMCE 皮肤提供的图标名称或 自定义图标。

类型： String

resizable

resizable 指定用户是否可以通过拖动侧边栏边缘来调整侧边栏大小。默认值为 false。

此功能仅适用于 TinyMCE 8.9 及更高版本。

当设置为 true 时，TinyMCE 会渲染一个调整大小手柄，并使用 sidebar_width、sidebar_min_width 和 sidebar_max_width 选项控制侧边栏宽度。对于 resizable 设置为 true 的侧边栏，其内容需遵循父元素的宽度。有关信息，请参阅：为可调整大小的侧边栏设置样式。

当省略 resizable 或将其设置为 false 时，TinyMCE 不渲染调整大小手柄，忽略这三个侧边栏宽度选项，并按该侧边栏内容样式定义的宽度渲染侧边栏。

类型： Boolean

onSetup

onSetup 指定首次创建面板时要调用的函数。该函数接收一个 API 对象，并应返回一个接受 API 的回调。默认值为 (api) => (api) => {}。

onSetup 是一个复杂的属性。它需要一个接受侧边栏 API 的函数，并应返回一个接受侧边栏 API 且无返回值的回调。这是因为只要侧边栏被渲染，onSetup 就会运行，而返回的回调会在侧边栏销毁时执行。因此，返回的函数本质上是一个 onTeardown 处理程序，可用于取消绑定事件和回调。

类型： Function

onShow

onShow 指定面板显示时要调用的函数。该函数接收一个 API 对象。

类型： Function

onHide

onHide 指定面板隐藏时要调用的函数。该函数接收一个 API 对象。

类型： Function

API 对象

element():HTMLElement

element():HTMLElement 函数返回侧边栏面板的根元素。

可调整大小的侧边栏

此功能仅适用于 TinyMCE 8.9 及更高版本。

用户可以通过向可编辑区域拖动侧边栏边缘或远离可编辑区域来调整侧边栏大小。TinyMCE 仅为 resizable 属性设置为 true 的侧边栏渲染调整大小手柄。

由 Comments 和 TinyMCE AI 插件注册的侧边栏默认可调整大小。当 tinymceai_sidebar_type 设置为 'floating' 时，TinyMCE AI 侧边栏不可调整大小。通过 addSidebar 注册的侧边栏默认不可调整大小，因此在 TinyMCE 8.9 之前创建的自定义侧边栏按之前的方式渲染。

sidebar_width、sidebar_min_width 和 sidebar_max_width 选项适用于编辑器中的每个可调整大小的侧边栏。TinyMCE 无法为单个侧边栏设置单独的宽度。

为可调整大小的侧边栏设置样式

不可调整大小的侧边栏的内容样式决定了侧边栏的渲染宽度。

tinymce.init({
  selector: 'textarea', // 根据 HTML 更改此值
  sidebar_show: 'mysidebar',
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      onShow: (api) => {
        const container = document.createElement('div');
        container.style.width = '600px';
        api.element().appendChild(container);
      },
    });
  }
});

TinyMCE 会设置可调整大小的侧边栏的宽度，因此内容样式需要遵循父元素的宽度，而不是设置固定宽度。将内容的宽度设置为 100%，使内容从 api.element() 继承宽度。

tinymce.init({
  selector: 'textarea', // 根据 HTML 更改此值
  sidebar_show: 'mysidebar',
  sidebar_width: 500,
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      resizable: true,
      onShow: (api) => {
        const container = document.createElement('div');
        container.style.width = '100%';
        api.element().appendChild(container);
      },
    });
  }
});

当 resizable 设置为 true 时，如果侧边栏的内容样式设置了固定宽度，则不会正确渲染。在启用该属性之前，请将内容样式更新为 100%。

持久化侧边栏宽度

TinyMCE 不会存储用户拖动侧边栏到的宽度。要在编辑器加载之间保持宽度，请存储 SidebarResized 事件报告的宽度，并在下次创建编辑器时将存储的值传递给 sidebar_width。

const storedWidth = window.localStorage.getItem('sidebar-width');

tinymce.init({
  selector: 'textarea', // 根据 HTML 更改此值
  sidebar_show: 'mysidebar',
  sidebar_width: storedWidth ? parseInt(storedWidth, 10) : 440,
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      resizable: true,
      onShow: (api) => {
        const container = document.createElement('div');
        container.style.width = '100%';
        api.element().appendChild(container);
      },
    });

    editor.on('SidebarResized', (e) => {
      window.localStorage.setItem('sidebar-width', e.width);
    });
  }
});

选项

sidebar_max_width

此选项设置用户可以将侧边栏拖动到的最大宽度（以像素为单位）。

该选项仅适用于注册时设置了 resizable 属性为 true 的侧边栏。用户无法调整未设置该属性的侧边栏的大小，TinyMCE 会忽略此选项。

此选项仅限制拖动操作。此选项不限制由 sidebar_width 设置的宽度，因此侧边栏可以打开得比此处设置的值更宽。

此功能仅在 TinyMCE 以 classic 模式运行时受支持。在 inline 模式下不受支持。有关编辑模式之间差异的更多信息，请参阅经典编辑模式。

类型：Number

默认值：800

示例：使用 sidebar_max_width

tinymce.init({
  selector: 'textarea', // 根据 HTML 更改此值
  sidebar_show: 'mysidebar',
  sidebar_max_width: 600,
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      resizable: true,
      onShow: (api) => {
        api.element().innerHTML = 'Hello world!';
      },
    });
  }
});

sidebar_max_width 选项的限制

可编辑区域不能缩小到 280 像素以下，此限制优先于 sidebar_max_width。有关此限制的信息，请参阅：sidebar_width 选项的限制。

在窄编辑器中，280 像素可编辑区域旁边剩余的宽度可能小于 sidebar_max_width 设置的值。在这种情况下，剩余的宽度将成为有效最大值，用户无法将侧边栏拖动超过该宽度。

sidebar_min_width

此选项设置用户可以将侧边栏拖动到的最小宽度（以像素为单位）。

该选项仅适用于注册时设置了 resizable 属性为 true 的侧边栏。用户无法调整未设置该属性的侧边栏的大小，TinyMCE 会忽略此选项。

此选项仅限制拖动操作。此选项不限制由 sidebar_width 设置的宽度，因此侧边栏可以打开得比此处设置的值更窄。

此功能仅在 TinyMCE 以 classic 模式运行时受支持。在 inline 模式下不受支持。有关编辑模式之间差异的更多信息，请参阅经典编辑模式。

类型：Number

默认值：300

示例：使用 sidebar_min_width

tinymce.init({
  selector: 'textarea', // 根据需要更改此值以匹配您的 HTML
  sidebar_show: 'mysidebar',
  sidebar_min_width: 400,
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      resizable: true,
      onShow: (api) => {
        api.element().innerHTML = 'Hello world!';
      },
    });
  }
});

sidebar_min_width 选项的限制

可编辑区域无法缩小至 280 像素以下，并且此限制的优先级高于 sidebar_min_width。有关此限制的信息，请参阅：sidebar_width 选项的限制。

当编辑器过窄而无法在 280 像素的可编辑区域旁边提供 sidebar_min_width 所设置的宽度时，TinyMCE 不会在拖动时调整侧边栏大小，侧边栏将保持当前宽度。

sidebar_show

此选项用于在编辑器初始化时显示指定的侧边栏。

此功能仅在 TinyMCE 以 classic 模式运行时支持。在 inline 模式下不受支持。有关编辑模式之间差异的更多信息，请参阅 Classic 编辑模式。

类型： 字符串

示例：使用 sidebar_show

tinymce.init({
  selector: 'textarea', // 根据需要更改此值以匹配您的 HTML
  sidebar_show: 'mysidebar',
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      onShow: (api) => {
        api.element().innerHTML = 'Hello world!';
      },
    });
  }
});

sidebar_width

此选项用于设置侧边栏在编辑器初始化时打开的宽度（以像素为单位）。

此选项仅适用于注册时设置了 resizable 属性为 true 的侧边栏。未设置该属性注册的侧边栏将保持该侧边栏内容样式所定义的宽度，且 TinyMCE 将忽略此选项。

sidebar_min_width 和 sidebar_max_width 选项不会限制此选项所设置的宽度。这些选项仅限制用户可以将侧边栏拖动到的宽度。可编辑区域的最小宽度确实会限制此宽度。有关此限制的信息，请参阅：sidebar_width 选项的限制。

此功能仅在 TinyMCE 以 classic 模式运行时支持。在 inline 模式下不受支持。有关编辑模式之间差异的更多信息，请参阅 Classic 编辑模式。

类型： 数字

默认值： 440

示例：使用 sidebar_width

tinymce.init({
  selector: 'textarea', // 根据需要更改此值以匹配您的 HTML
  sidebar_show: 'mysidebar',
  sidebar_width: 500,
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      resizable: true,
      onShow: (api) => {
        api.element().innerHTML = 'Hello world!';
      },
    });
  }
});

sidebar_width 选项的限制

可编辑区域和侧边栏共享同一个容器。为了保持可编辑区域的可用性，TinyMCE 不允许可编辑区域缩小至 280 像素以下。此限制是固定的，且优先级高于 sidebar_width、sidebar_min_width 和 sidebar_max_width。

当编辑器过窄而无法在 280 像素的可编辑区域旁边提供所请求的宽度时，TinyMCE 会将侧边栏缩减至剩余的宽度。例如，在宽度为 1000 像素的编辑器中，sidebar_width 设置为 2000 时，侧边栏的宽度将约为 716 像素，因为可编辑区域占用了 280 像素，而编辑器边框占据了剩余的像素。

tinymce.init 中的示例

有关创建用户可调整大小的侧边栏的信息，请参阅：可调整大小的侧边栏。

tinymce.init({
  ...
  toolbar: 'mysidebar',
  setup: (editor) => {
    editor.ui.registry.addSidebar('mysidebar', {
      tooltip: '我的侧边栏',
      icon: 'comment',
      resizable: true,
      onSetup: (api) => {
        console.log('渲染面板', api.element());
        return () => {
          console.log('移除侧边栏');
        };
      },
      onShow: (api) => {
        console.log('显示面板', api.element());
        api.element().innerHTML = 'Hello world!';
      },
      onHide: (api) => {
        console.log('隐藏面板', api.element());
      }
    });
  }
});

TinyMCE 插件中的示例

有关创建用户可调整大小的侧边栏的信息，请参阅：可调整大小的侧边栏。

tinymce.PluginManager.add('myplugin', (editor) => {
  editor.ui.registry.addSidebar('mysidebar', {
    tooltip: '我的侧边栏',
    icon: 'comment',
    resizable: true,
    onSetup: (api) => {
      console.log('渲染面板', api.element());
      return () => {
        console.log('移除侧边栏');
      };
    },
    onShow: (api) => {
      console.log('显示面板', api.element());
      api.element().innerHTML = 'Hello world!';
    },
    onHide: (api) => {
      console.log('隐藏面板', api.element());
    }
  });
});