120 lines
7.2 KiB
Markdown
120 lines
7.2 KiB
Markdown
### 区块脚本与样式
|
||
|
||
在构建区块时，推荐使用 `block.json` 来加载区块本身所需的所有脚本和样式。您可以为编辑器、前端或两者同时加载资源。详见[区块元数据](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)文档。
|
||
|
||
### 主题脚本与样式
|
||
|
||
若需在主题中加载编辑器JavaScript，可参照上文使用 `enqueue_block_assets` 或 `enqueue_block_editor_assets`。编辑器专用样式表应始终通过 [`add_editor_style()`](https://developer.wordpress.org/reference/functions/add_editor_style/) 或 [`wp_enqueue_block_style()`](https://developer.wordpress.org/reference/functions/wp_enqueue_block_style/) 添加。
|
||
|
||
`wp_enqueue_block_style()` 函数支持在编辑器及前端加载逐区块样式表。结合 `theme.json` 使用，这是样式化区块的最佳方案之一。更多细节请参阅WordPress开发者博客文章[运用theme.json与逐区块样式打造高性能主题](https://developer.wordpress.org/news/2022/12/leveraging-theme-json-and-per-block-styles-for-more-performant-themes/)。
|
||
|
||
## 向后兼容性与已知问题
|
||
|
||
通常而言，在iframe模式编辑器中加载的资源，在WordPress 6.3+版本的非iframe模式下也会同步加载，但反向兼容并不总是成立。
|
||
|
||
若您开发的插件或主题需兼容6.2及以下版本，同时保持与WordPress 6.3的兼容性，则无法使用 `enqueue_block_assets` 钩子——因为在6.3之前该钩子不会在iframe编辑器内容中加载资源。
|
||
|
||
替代方案是使用 `enqueue_block_editor_assets`，只要加载的样式表包含以下任一选择器：`.editor-styles-wrapper`、`.wp-block` 或 `.wp-block-*`。控制台会显示警告信息，但该钩子仍会将样式应用于编辑器内容。
|
||
|
||
需特别注意：从WordPress 6.3开始，为保持向后兼容，通过 `enqueue_block_assets` 加载的资源会在编辑器iframe内外同时加载。根据所加载的脚本库不同，这可能引发问题。Gutenberg项目的[GitHub代码库](https://github.com/WordPress/gutenberg/issues/53590)正在持续讨论这一机制。
|
||
|
||
如果您在使用本指南所述方法时遇到未被报告过的问题，请在GitHub上[提交问题报告](https://github.com/WordPress/gutenberg/issues/new/choose)。
|
||
|
||
# 在编辑器中加载资源
|
||
|
||
本指南旨在成为在编辑器中加载资源（脚本和样式）的权威参考。这里概述的方法代表了推荐实践，但请注意，随着WordPress的发展，本资源也会不断更新。欢迎贡献更新内容。
|
||
|
||
自WordPress 6.3起，如果所有已注册区块都具备[`区块API版本3`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)或更高版本，且未注册传统元框，则文章编辑器将采用iframe嵌入。站点编辑器始终采用iframe嵌入。本指南假设您需要为iframe嵌入的编辑器加载资源，但请参考下文的后向兼容性章节了解其他注意事项。
|
||
|
||
若需了解编辑器为何采用iframe嵌入，请重温[iframe嵌入（模板）编辑器中的区块](https://make.wordpress.org/core/2021/06/29/blocks-in-an-iframed-template-editor/)这篇文章。
|
||
|
||
## 编辑器与编辑器内容
|
||
在编辑器中加载资源前，首先需要明确目标范围。
|
||
|
||
您是要为用户生成内容（区块）添加样式或JavaScript？还是要修改编辑器用户界面组件或与编辑器API交互？这可能包括从创建自定义区块控件到注册区块变体等各种场景。
|
||
|
||
根据这些问题的答案，需要使用不同的钩子。如果您正在构建区块或主题，还需要考虑其他方法。请参考下文对应章节。
|
||
|
||
## 资源加载场景
|
||
### 编辑器脚本与样式
|
||
|
||
当需要为编辑器本身（即非用户生成内容）加载资源时，应使用[`enqueue_block_editor_assets`](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/)钩子，配合标准的[`wp_enqueue_script`](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)和[`wp_enqueue_style`](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)函数。
|
||
|
||
典型应用场景包括：添加自定义检查器或工具栏控件、通过JavaScript注册区块样式和变体、注册编辑器插件等。
|
||
|
||
```php
|
||
/**
|
||
* 加载编辑器资源
|
||
*/
|
||
function example_enqueue_editor_assets() {
|
||
wp_enqueue_script(
|
||
'example-editor-scripts',
|
||
plugins_url( 'editor-scripts.js', __FILE__ )
|
||
);
|
||
wp_enqueue_style(
|
||
'example-editor-styles',
|
||
plugins_url( 'editor-styles.css', __FILE__ )
|
||
);
|
||
}
|
||
add_action( 'enqueue_block_editor_assets', 'example_enqueue_editor_assets' );
|
||
```
|
||
|
||
虽然不推荐，但需注意出于后向兼容考虑，`enqueue_block_editor_assets`也可用于设置编辑器内容样式。详见下文说明。
|
||
|
||
### 编辑器内容脚本与样式
|
||
|
||
自WordPress 6.3起，所有通过[`enqueue_block_assets`](https://developer.wordpress.org/reference/hooks/enqueue_block_assets/)PHP操作添加的资源都会在iframe嵌入的编辑器中加载。详见[#48286](https://github.com/WordPress/gutenberg/pull/48286)。
|
||
|
||
这是为用户生成内容（区块）加载资源的主要方法，该钩子会在编辑器环境和网站前端同时触发。不应用于添加针对编辑器UI的资源或与编辑器API交互。后向兼容性说明详见下文。
|
||
|
||
某些情况下可能只需在编辑器中加载资源而不在前端加载。可通过[`is_admin()`](https://developer.wordpress.org/reference/functions/is_admin/)检测实现。
|
||
|
||
```php
|
||
/**
|
||
* 仅限编辑器内加载内容资源
|
||
*/
|
||
function example_enqueue_editor_content_assets() {
|
||
if ( is_admin() ) {
|
||
wp_enqueue_script(
|
||
'example-editor-content-scripts',
|
||
plugins_url( 'content-scripts.js', __FILE__ )
|
||
);
|
||
wp_enqueue_style(
|
||
'example-editor-content-styles',
|
||
plugins_url( 'content-styles.css', __FILE__ )
|
||
);
|
||
}
|
||
}
|
||
add_action( 'enqueue_block_assets', 'example_enqueue_editor_content_assets' );
|
||
```
|
||
|
||
也可使用[`block_editor_settings_all`](https://developer.wordpress.org/reference/hooks/block_editor_settings_all/)钩子直接修改编辑器设置。此方法实现稍复杂但灵活性更高，仅当`enqueue_block_assets`无法满足需求时使用。
|
||
|
||
以下示例将所有段落默认文字颜色设为`绿色`：
|
||
|
||
```php
|
||
/**
|
||
* 通过添加自定义样式修改编辑器设置
|
||
*
|
||
* @param array $editor_settings 包含当前编辑器设置的数组
|
||
* @param string $editor_context 编辑器上下文
|
||
*
|
||
* @return array 添加自定义CSS样式后的编辑器设置
|
||
*/
|
||
function example_modify_editor_settings( $editor_settings, $editor_context ) {
|
||
$editor_settings["styles"][] = array(
|
||
"css" => 'p { color: green }'
|
||
);
|
||
|
||
return $editor_settings;
|
||
}
|
||
add_filter( 'block_editor_settings_all', 'example_modify_editor_settings', 10,2 );
|
||
```
|
||
|
||
这些样式会以内联方式插入iframe编辑器的`body`中，并添加`.editor-styles-wrapper`前缀。最终生成的标记如下：
|
||
|
||
```css
|
||
<style>.editor-styles-wrapper p { color: green; }</style>
|
||
```
|
||
|
||
从WordPress 6.3开始，还可通过这种修改编辑器设置的方法，使用JavaScript动态更改样式。详见[#52767](https://github.com/WordPress/gutenberg/pull/52767#top)。 |