在编辑器中排队资源

本指南旨在作为在编辑器中排队资源(脚本和样式)的最终参考。这里概述的方法代表了推荐的实践,但请记住,该资源将随着WordPress的发展而发展。鼓励更新。

从WordPress 6.3开始,如果所有注册的块都有一个块API版本3或更高版本,并且没有注册传统的元框。站点编辑器始终是iframed。本指南假设您正在为iframed Editor排队资源,但有关其他注意事项,请参阅下面的向后兼容性部分。

有关编辑被框架化的原因的更多信息,请重新访问帖子iframed(模板)编辑器中的块.

编辑器与编辑器内容

在编辑器中排队资源之前,必须首先确定要尝试的目标。

您想在编辑器中为用户生成的内容(块)添加样式或JavaScript吗?还是要修改编辑器用户界面(UI)组件或与编辑器API交互?这可能包括从创建自定义块控件到注册块变体的所有内容。

根据这些问题的答案,可以使用不同的钩子,如果您正在构建块或主题,还需要考虑其他方法。请参阅以下指定部分。

排队资产的场景

编辑器脚本和样式

每当需要为编辑器本身(即不是用户生成的内容)排队资源时,应使用排队块编辑器资产与标准挂钩wp_排队_脚本wp_enque_样式功能。

例如,添加自定义检查器或工具栏控件、在JavaScript中注册块样式和变体、注册编辑器插件等。

/***将编辑器资源排队。*/函数示例_enqueue_editor_assets(){wp_排队_脚本('示例编辑器脚本',插件url('editor-scripts.js',__FILE__));wp_排队_样式(“编辑样式示例”,plugins_url('editor-styles.css',__FILE__));}add_action(“enqueue_block_editor_assets”,“example_enqueue_Eeditor_aassets”);

虽然不是推荐的方法,但重要的是要注意排队块编辑器资产可用于设置编辑器内容的样式,以实现向后兼容性。有关更多详细信息,请参见下文。

编辑器内容脚本和样式

从WordPress 6.3开始,所有通过排队块资产PHP操作也将在iframed Editor中排队。请参见#48286了解更多详细信息。

这是将用户生成的内容(块)的资产排队的主要方法,此钩子在编辑器和站点前端都会触发。它不应用于添加用于编辑器UI的资产或与编辑器API交互。有关向后兼容性的说明,请参见下文。

在某些情况下,您可能只想在编辑器中添加资源,而不想在前端添加资源。您可以通过使用is_admin()检查。

/***将内容资源排入队列,但仅在编辑器中。*/函数示例_enqueue_editor_content_assets(){if(is_admin()){wp_排队_脚本('示例-编辑器内容-脚本',插件url('content-scripts.js',__FILE__));wp_排队_样式('示例-编辑器内容样式',plugins_url('content-styles.css',__FILE__));}}add_action('enqueue_block_assets','example_enqueue_editor_content_assets`);

你也可以用钩子块编辑器设置全部直接修改编辑器设置。此方法的实现稍微复杂一些,但提供了更大的灵活性。只有在以下情况下才能使用排队块资产无法满足您的需求。

以下示例将所有段落的默认文本颜色设置为绿色.

/***通过添加自定义样式修改编辑器设置。**@param array$editor_settings包含当前编辑器设置的数组。*@param string$editor_context编辑器的上下文。**@return array使用添加的自定义CSS样式修改了编辑器设置。*/函数示例_modify_editor_settings($editor_ssettings,$editor_context){$editor_settings[“styles”][]=数组(“css”=>'p{color:green}');返回$editor_settings;}add_filter('block_editor_settings_all','example_modify_editor_settings',10,2);

这些样式在身体iframed Editor的.editor样式包装器。生成的标记如下所示:

editor-styles-wrapper p{color:green;}

从WordPress 6.3开始,您还可以使用这种修改编辑器设置的方法,使用JavaScript动态更改样式。请参见#52767了解更多详细信息。

阻止脚本和样式

构建块时,块.json是将块本身特别需要的所有脚本和样式排队的推荐方法。您可以为编辑器、前端或两者排队资源。请参阅块元数据文章了解更多详细信息。

主题脚本和样式

如果需要在主题中排队Editor JavaScript,可以使用排队块资产排队块编辑器资产如上所述。特定于编辑器的样式表几乎总是应该添加添加编辑器样式()wp_enqueue_block_style().

这个wp_enqueue_block_style()函数允许您在编辑器和前端加载每个块的样式表。主题.json,这是设计块的最佳方法之一。查看WordPress开发者博客文章利用theme.json和per-block样式实现更高性能的主题了解更多详细信息。

向后兼容性和已知问题

一般来说,当您在iframed Editor中排队时,只要您使用WordPress 6.3+,当编辑器没有iframed时,资产也会排队。反之亦然。

假设您正在构建一个插件或主题,该插件或主题需要向后兼容6.2或更低版本,同时保持与WordPress 6.3的兼容性。在这种情况下,您将无法使用排队块资产因为这个钩子不会将6.3之前的iframed Editor内容中的资产排队。

作为替代,您可以使用排队块编辑器资产只要排队的样式表至少包含以下选择器之一:.editor样式包装器,.wp-块,或.wp-块-*。控制台中将记录一条警告消息,但挂钩会将样式应用于编辑器的内容。

值得注意的是,从WordPress 6.3开始,资产排队排队块资产在编辑器的iframe内外加载以实现向后兼容性。根据您尝试排队的脚本库,这可能会导致问题。关于这种方法的讨论正在古腾堡进行GitHub存储库.

如果您在使用本指南中概述的任何方法时遇到以前未报告过的问题,请提交问题在GitHub上。