可用事件

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

处理编辑器事件

TinyMCE 支持多种类型的事件，可用于编辑器和插件。

支持的浏览器原生事件
编辑器核心事件
插件事件
编辑器管理器事件

以下示例展示了如何在 TinyMCE 中使用支持的原生事件、编辑器核心事件和插件事件。编辑器管理器事件使用 tinymce.on 单独处理，而非 editor.on。

定义事件处理程序

事件处理程序可以通过 editor.on 方法在任意位置初始化，如下例所示：

tinymce.activeEditor.on('click', (e) => {
  console.log('编辑器被点击，位置：' + e.pageX + ', ' + e.pageY);
});

`setup` 和 `init_instance_callback` 选项

设置事件的常见用法是使用 setup 和 init_instance_callback 选项。这些选项允许你在编辑器实例初始化之前和之后绑定事件。

setup 选项可用于在编辑器实例初始化之前绑定事件。

init_instance_callback 选项可用于在编辑器实例初始化之后绑定事件。

init_instance_callback 在功能上等同于在 setup 选项中为 init 事件绑定事件监听器。

例如，以下代码：

tinymce.init({
  selector: 'textarea',
  setup: (editor) => {
    editor.on('init', (e) => {
      console.log('编辑器已初始化。');
    });
  }
});

等同于：

tinymce.init({
  selector: 'textarea',
  init_instance_callback: (editor) => {
    console.log('编辑器已初始化。');
  }
});

有关这些选项的更多信息，请参阅 setup 和 init_instance_callback。

在编辑器初始化前绑定事件

以下示例使用 setup 选项在编辑器实例初始化之前绑定事件。这是一个处理不返回数据的事件（如 ResizeEditor 编辑器事件）的示例。因此，e 参数未被使用。

tinymce.init({
  selector: 'textarea',
  setup: (editor) => {
    editor.on('ResizeEditor', (e) => {
      console.log('编辑器大小已调整。');
    });
  }
});

在编辑器初始化后绑定事件

以下示例使用 init_instance_callback 选项在编辑器实例初始化之后绑定事件。这是一个处理返回数据的事件（如 ExecCommand 事件）的示例。因此，我们可以使用 e 参数来访问事件返回的数据。

tinymce.init({
  selector: 'textarea',
  init_instance_callback: (editor) => {
    editor.on('ExecCommand', (e) => {
      console.log(`触发了 ${e.command} 命令。`);
    });
  }
});

示例：内容更改回调

要在编辑器内容更改时运行回调，请在 setup 选项中使用 Change 事件和 editor.on()：

tinymce.init({
  selector: 'textarea',
  setup: (editor) => {
    editor.on('change', () => {
      console.log('内容已修改。');
    });
  }
});

当内容更改被提交时（例如，当焦点从编辑器移开时），会触发 Change 事件。如需在用户输入时实时更新，请改用 input 事件。

支持的浏览器原生事件

TinyMCE 支持以下浏览器原生事件。点击事件名称查看详情（链接打开 MDN Web 文档）。

编辑器核心事件

以下事件由 TinyMCE 编辑器提供。

名称	数据	描述
activate	`{ relatedTarget: Editor }`	当编辑器被激活时触发。
deactivate	`{ relatedTarget: Editor }`	当编辑器被停用时触发。
remove	N/A	在编辑器被移除/销毁之前触发。
detach	N/A	在移除事件之后，编辑器容器从 DOM 中分离之前触发。
init	N/A	当编辑器完全初始化时触发。
ScrollIntoView	`{ elm: HTMLElement, alignToTop: boolean }`	当某个元素即将滚动到可视区域时触发。
AfterScrollIntoView	`{ elm: HTMLElement, alignToTop: boolean }`	当某个元素已经滚动到可视区域时触发。
ObjectResized	`{ target: HTMLElement, width: number, height: number, origin: string }`	当对象（例如图像）完成调整大小操作时触发。
ObjectResizeStart	`{ target: HTMLElement, width: number, height: number, origin: string }`	当对象（例如图像）即将调整大小时触发。
SwitchMode	`{ mode: string }`	当编辑器模式更改时触发。可用模式为 "design"（设计）和 "readonly"（只读）。其他模式可以通过 TinyMCE API 'tinymce.activeEditor.mode.register()' 进行注册。
DisabledStateChange	{ state: boolean }	当编辑器禁用模式状态改变时触发。
ScrollWindow	(与原生 scroll event 的数据相同)	当窗口滚动时触发。
ResizeWindow	(与原生 resize event 的数据相同)	当窗口大小调整时触发。
BeforeExecCommand	`{ command: string, ui?: boolean, value?: any }`	在执行命令之前触发。
ExecCommand	`{ command: string, ui?: boolean, value?: any }`	在执行命令之后触发。
NodeChange	`{ element: Element, parents: Node[], selectionChange?: boolean }`	当编辑器内容中所选节点发生变化时触发。
FormatApply	`{ format: string; vars?: FormatVars; node?: Node \| RangeLikeObject }`	在应用格式后触发。
FormatRemove	`{ format: string; vars?: FormatVars; node?: Node \| RangeLikeObject }`	在移除格式后触发。
ShowCaret	`{ target: Node, direction: number, before: boolean }`	在编辑器中显示伪光标元素之前触发。伪光标将出现在通常不显示光标的位置，例如表格的开头或结尾以及不可编辑内容处。
SelectionChange	不适用	当编辑器中的内容选择发生变化时触发。
ObjectSelected	`{ target: Node, targetClone?: Node }`	当在编辑器中选择了一个对象（如图像）且选择元素已渲染时触发。
BeforeObjectSelected	`{ target: Node, targetClone?: Node }`	当在编辑器中选择了一个对象（如图像）但在其渲染为已选状态之前触发。
GetSelectionRange	`{ range: Range }`	当从编辑器获取选择范围时触发。
SetSelectionRange	`{ range: Range, forward: boolean }`	在编辑器中设置选择范围之前触发。
AfterSetSelectionRange	`{ range: Range, forward: boolean }`	在编辑器中设置选择范围之后触发。
BeforeGetContent	`{ format: string, source_view?: boolean, selection?: boolean, save?: boolean }`	在编辑器内容序列化之前触发。
GetContent	`{ content: string, format: string, source_view?: boolean, selection?: boolean, save?: boolean }`	在编辑器内容序列化之后触发。
BeforeSetContent	`{ content: string, format?: string, paste?: boolean, selection?: boolean }`	在内容解析并渲染到编辑器之前触发。
SetContent	`{ content: string, format?: string, paste?: boolean, selection?: boolean }`	在内容解析并渲染到编辑器之后触发。注意：`content` 属性已被弃用，并将在下一个主要版本中移除。
LoadContent	不适用	在初始内容加载到编辑器之后触发。
PreviewFormats	不适用	当在编辑器中预览格式时，在生成格式 CSS 之前触发。
AfterPreviewFormats	不适用	当在编辑器中预览格式时，在生成格式 CSS 之后触发。
ScriptsLoaded	不适用	当编辑器运行所需的所有脚本（如插件和主题）加载完成时触发。
PreInit	不适用	在加载编辑器之后且开始加载编辑器内容之前触发。
PostRender	不适用	在主题渲染完成后触发。
NewBlock	`{ newBlock: Element }`	当在编辑器中创建新块时触发，例如用户按下回车键时。
ClearUndos	不适用	当撤销级别被清除时触发。
TypingUndo	不适用	当通过在编辑器中输入内容创建新的撤销级别时触发。
Change	`{ level: UndoLevel }`	当编辑器内容变更被提交时触发，例如焦点移出编辑器时。
Redo	`{ level: UndoLevel }`	当变更被重新应用时触发。
Undo	`{ level: UndoLevel }`	当变更被撤销时触发。
BeforeAddUndo	`{ level: UndoLevel, lastLevel: UndoLevel, originalEvent: Event }`	在创建新的撤销级别之前触发。
AddUndo	`{ level: UndoLevel, lastLevel: UndoLevel, originalEvent: Event }`	在创建新的撤销级别之后触发。
Dirty	不适用	当编辑器从“原始”状态转换为“脏”状态时触发。当自初始化或上次保存状态以来创建了一个撤销级别时，编辑器即为“脏”状态。要检查编辑器是否为“脏”状态，请使用 `editor.isDirty` API。
CloseWindow	`{ dialog: DialogApi }`	当对话框关闭时触发。
OpenWindow	`{ dialog: DialogApi }`	当对话框打开时触发。
ProgressState	`{ state: boolean, time?: number }`	当使用TinyMCE API `tinymce.activeEditor.setProgressState()` 安排编辑器进度状态的更改时触发。
AfterProgressState	`{ state: boolean }`	编辑器进度状态更改后触发，且新的进度状态生效。
PreProcess	`{ node: Element, format: string }`	在将DOM节点序列化为HTML内容之前触发。
PostProcess	`{ node: Element, format: string }`	在将DOM节点序列化为HTML内容之后触发。
SetAttrib	`{ attrElm: Element, attrName: string, attrValue: string }`	当使用编辑器 DOMUtils API 更新属性时触发。
ResizeEditor	N/A	当编辑器大小调整时触发，无论是通过调整大小手柄还是自动调整大小插件。在TinyMCE 6.1及更高版本中，当切换全屏模式时也会触发此事件。切换全屏模式需要启用 `fullscreen` 插件。
SkinLoaded	N/A	当编辑器皮肤加载完成时触发。
SkinLoadError	`{ message: string }`	当编辑器皮肤加载失败时触发。
ThemeLoadError	`{ message: string }`	当编辑器主题加载失败时触发。
ModelLoadError	`{ message: string }`	当编辑器模型加载失败时触发。
PluginLoadError	`{ message: string }`	当编辑器插件加载失败时触发。
IconsLoadError	`{ message: string }`	当编辑器图标包加载失败时触发。
LanguageLoadError	`{ message: string }`	当编辑器语言包加载失败时触发。
BeforeRenderUI	N/A	在渲染主题UI之前触发。
ToggleSidebar	N/A	当侧边栏被打开/关闭切换时触发。
SidebarResizeStart	N/A	当用户开始拖动侧边栏的调整大小手柄时触发。此事件要求侧边栏注册时 `resizable` 属性设置为 `true`。
SidebarResized	`{ width: number }`	当用户停止拖动侧边栏的调整大小手柄时触发。`width` 是调整大小后侧边栏的宽度，以像素为单位。此事件要求侧边栏注册时 `resizable` 属性设置为 `true`。
longpress	(Same data as the native touchstart event)	当在编辑器内的触摸设备上发生长按操作时触发。
tap	(Same data as the native touchend event)	当在编辑器内的触摸设备上发生点击操作时触发（模拟类似click的事件）。
ScrollContent	(Same data as the native scroll event)	(仅限iframe模式) 当iframe窗口内的内容滚动时触发。
ResizeContent	(Same data as the native resize event)	(仅限iframe模式) 当iframe窗口大小调整时触发。
Load	N/A	(仅限iframe模式) 当编辑器iframe内容加载完成时触发。
ResolveName	`{ name: string, target: Element }`	(仅限iframe模式) 当编辑器尝试解析元素的名称以渲染状态栏路径时触发。
BeforeOpenNotification	`{ notification: NotificationSpec }`	在显示通知之前触发。有关通知规范（`NotificationSpec`）的信息，请参阅：创建自定义通知。
OpenNotification	`{ notification: NotificationApi }`	在显示通知之后触发。有关通知API（`NotificationApi`）的信息，请参阅：创建自定义通知。
PastePreProcess	`{ content: string }`	在从剪贴板解析内容之前触发。
PastePostProcess	`{ node: Element }`	在从剪贴板解析内容之后但在添加到编辑器之前触发。
PastePlainTextToggle	`{ state: boolean }`	纯文本粘贴模式状态发生变化时触发。
AutocompleterStart	`{ lookupData: AutocompleteLookupData[] }`	当自动完成器被触发且应显示获取的建议时触发。
AutocompleterUpdate	`{ lookupData: AutocompleteLookupData[] }`	当内容发生变化且活动的自动完成器需要更新显示的建议时触发。
AutocompleterEnd	N/A	当活动的自动完成器菜单即将关闭时触发。
NewRow	N/A	当创建新的表格行时触发。
NewCell	N/A	当创建新的表格单元格时触发。
TableModified	`{ table: HTMLTableElement, structure: boolean, style: boolean }`	当表格发生样式或结构更改时触发。
TableSelectionClear	N/A	当表格选择被清除时触发。
StylesTextUpdate	`{ value: string }`	当`styles`定制工具栏按钮的可见文本标签更新后触发。`value` 指的是更新后的可见文本标签。
BlocksTextUpdate	`{ value: string }`	当`blocks`定制工具栏按钮的可见文本标签更新后触发。`value` 指的是更新后的可见文本标签。
AlignTextUpdate	`{ value: string }`	当`align`定制工具栏按钮的可见图标更新后触发。`value` 指的是更新后的可见图标。
FontSizeTextUpdate	`{ value: string }`	当`fontsize`定制工具栏按钮的可见文本标签更新后触发。`value` 指的是更新后的可见文本标签。
FontSizeInputTextUpdate	`{ value: string }`	当`fontsizeinput`定制工具栏按钮的可见文本标签更新后触发。`value` 指的是更新后的可见文本标签。
FontFamilyTextUpdate	`{ value: string }`	当`fontfamily`定制工具栏按钮的可见文本标签更新后触发。`value` 指的是更新后的可见文本标签。

插件事件

以下插件提供事件。

无障碍检查器事件
自动保存事件
字符映射事件
评论事件
格式刷事件
全屏事件
导入 CSS 事件
链接检查器事件
列表事件
媒体嵌入事件
永久笔事件
PowerPaste 事件
拼写检查器事件
修订历史事件
拼写自动更正事件
可视化块事件
可视化字符事件
字数统计事件

无障碍检查器事件

以下事件由无障碍检查器插件提供。

名称	数据	描述
A11ycheckStart	N/A	当无障碍检查器`打开`时触发
A11ycheckStop	N/A	当无障碍检查器`关闭`时触发
A11ycheckIgnore	N/A	当按下`忽略`按钮时触发
A11ycheckRepair	N/A	当按下`修复`按钮时触发
A11ycheckShowDetails	N/A	当按下`点击获取更多信息`按钮时触发

自动保存事件

以下事件由自动保存插件提供。

名称	数据	描述
RestoreDraft	N/A	当草稿已恢复时触发。
StoreDraft	N/A	当草稿已保存时触发。
RemoveDraft	N/A	当草稿已从内存中移除时触发。

字符映射事件

以下事件由字符映射插件提供。

名称	数据	描述
InsertCustomChar	`{ chr: string }`	在特殊字符插入编辑器之前触发。

评论事件

以下事件由Tiny 评论插件提供。

名称	数据	描述
mce-tinycomments-update	N/A	当评论侧边栏打开或关闭时触发。
CommentChange	`{ getEventLog: () ⇒ EventLog[] }`	当添加、解决、删除、编辑或回复评论时触发。

格式刷事件

以下事件由格式刷插件提供。

名称	数据	描述
FormatPainterToggle	`{ state: boolean }`	当格式刷状态改变时触发。

全屏事件

以下事件由全屏插件提供。

名称	数据	描述
FullscreenStateChanged	`{ state: boolean }`	当全屏状态改变时触发。

导入CSS事件

以下事件由导入CSS插件提供。

名称	数据	描述
AddStyleModifications	`{ items: StyleItem[], replace: boolean }`	当编辑器初始化期间从CSS中解析出样式修改时触发。

链接检查器事件

以下事件由链接检查器插件提供。

名称	数据	描述
LinkCheckerError	`{ message: string }`	当发生链接检查器错误时触发，例如无法连接到链接检查器服务。

列表事件

以下事件由列表插件提供。

名称	数据	描述
ListMutation	`{ action: string, element: Element }`	当列表切换开启/关闭时触发。

媒体嵌入事件

以下事件由媒体嵌入插件提供。

名称	数据	描述
MediaEmbedError	`{ message: string }`	当发生媒体嵌入错误时触发，例如无法连接到媒体嵌入服务。

永久钢笔事件

以下事件由永久钢笔插件提供。

名称	数据	描述
PermanentPenToggle	`{ state: boolean }`	当永久钢笔状态改变时触发。
PermanentPenProperties	`{ fontname: string, fontcolor: string, fontsize: string, hilitecolor: string, bold: boolean, italic: boolean, underline: boolean, strikethrough: boolean }`	当永久钢笔属性改变时触发。

PowerPaste事件

以下事件由PowerPaste插件提供。

名称	数据	描述
PastePreProcess	`{ content: string, mode: string, source: string }`	在内容从剪贴板解析之前触发。
PastePostProcess	`{ node: Element, mode: string, source: string }`	在内容从剪贴板解析之后，但在添加到编辑器之前触发。
PastePlainTextToggle	`{ state: boolean }`	当纯文本粘贴模式状态改变时触发。

修订历史事件

以下事件由修订历史插件提供。

名称	数据	描述
VersionRestored	`{ revisionId: string }`	当版本被恢复时触发。

拼写检查器事件

以下事件由拼写检查器插件提供。

名称	数据	描述
SpellcheckerIgnore	`{ word: string }`	当单词的单个实例被标记为忽略时触发。
SpellcheckerIgnoreAll	`{ word: string, language: string }`	当单词（在某种语言中）的所有实例被标记为忽略时触发。
SpellcheckError	`{ message: string }`	当发生拼写检查器错误时触发，例如当无法连接到拼写检查器服务时。
SpellcheckStart	N/A	当启用拼写检查时触发。
SpellcheckEnd	N/A	当禁用拼写检查时触发。
SpellcheckerLanguageChanged	`{ language: string, prevLanguage: string }`	当拼写检查语言更改时触发。
SpellcheckerUpdated	`{ spelling: SpellingUpdate }`	当编辑器内容被检查拼写错误时触发，并在 `spelling` 对象中包含建议。

拼写自动校正事件

以下事件由拼写自动校正插件提供。

名称	数据	描述
AutocorrectStart	无	当自动校正从关闭状态开启时触发。
AutocorrectEnd	无	当自动校正从开启状态关闭时触发。
CapitalizeStart	无	当大写功能从关闭状态开启时触发。
CapitalizeEnd	无	当大写功能从开启状态关闭时触发。

可视化区块事件

以下事件由可视化区块插件提供。

名称	数据	描述
VisualBlocks	`{ state: boolean }`	当可视化区块状态发生变化时触发。

可视化字符事件

以下事件由可视化字符插件提供。

名称	数据	描述
VisualChars	`{ state: boolean }`	当可视化字符状态发生变化时触发。

字数统计事件

以下事件由字数统计插件提供。

名称	数据	描述
WordCountUpdate	`{ wordCount: { words: number, characters: number, charactersWithoutSpaces: number } }`	当编辑器字数统计更新时触发。

编辑器管理器事件

以下事件用于编辑器管理。这些事件通过 tinymce.on 处理，而不是通过 editor.on 或 editor.fire ，如示例“处理编辑器管理器事件”所示。

名称	数据	描述
AddEditor	`{ editor: Editor}`	当创建新的编辑器时触发。
RemoveEditor	`{ editor: Editor}`	当编辑器被移除/销毁时触发。
BeforeUnload	无	在浏览器窗口关闭前触发（与原生 `beforeunload` 事件相同）。

示例：处理编辑器管理器事件

AddEditor

tinymce.on('AddEditor', (e) => {
  console.log('Added editor with id: ' + e.editor.id);
});

RemoveEditor

tinymce.on('RemoveEditor', (e) => {
  console.log('Removed editor with id: ' + e.editor.id);
});