本指南旨在作为在编辑器中排队资源(脚本和样式)的最终参考。这里概述的方法代表了推荐的实践,但请记住,该资源将随着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上。