### `media.crossOrigin`

此过滤器用于为外部来源的媒体元素（即 `<audio>`、`<img>`、`<link>`、`<script>`、`<video>`）设置或修改 `crossOrigin` 属性。关于 `crossOrigin` 属性的详细信息、其取值以及如何应用于各元素，请参阅此[文章](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin)。

一个实际应用的例子是在图片块的转换功能中，允许跨域图片在 `<canvas>` 中使用。示例如下：

```js
import { addFilter } from '@wordpress/hooks';

addFilter(
	'media.crossOrigin',
	'my-plugin/with-cors-media',
	// 回调函数接受第二个参数 `mediaSrc`，它引用了实际外部媒体的 URL，
	// 如果您想基于此 URL 决定 crossOrigin 的值，这将非常有用。
	( crossOrigin, mediaSrc ) => {
		if ( mediaSrc.startsWith( 'https://example.com' ) ) {
			return 'use-credentials';
		}
		return crossOrigin;
	}
);
```

## 编辑器 REST API 预加载路径

您可以使用 [`block_editor_rest_api_preload_paths`](https://developer.wordpress.org/reference/hooks/block_editor_rest_api_preload_paths/) 来过滤 REST API 路径数组，这些路径将用于预加载块编辑器中常用的数据。示例如下：

```php
add_filter( 'block_editor_rest_api_preload_paths', 'example_filter_block_editor_rest_api_preload_paths_when_post_provided', 10, 2 );

function example_filter_block_editor_rest_api_preload_paths_when_post_provided( $preload_paths, $editor_context ) {
	if ( ! empty( $editor_context->post ) ) {
		array_push( $preload_paths, array( '/wp/v2/blocks', 'OPTIONS' ) );
	}
	return $preload_paths;
}
```

## 记录错误

用户界面某部分的 JavaScript 错误不应导致整个应用崩溃。为了解决用户的问题，React 库使用了 ["错误边界"](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) 的概念。错误边界是 React 组件，可以捕获其子组件树中任何位置的 JavaScript 错误，并显示备用 UI，而不是崩溃的组件树。

`editor.ErrorBoundary.errorLogged` 操作允许您接入 [错误边界](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)，并让您访问错误对象。

您可以使用此操作获取由错误边界处理的错误对象。例如，您可能希望将它们发送到外部错误跟踪工具。示例如下：

```js
import { addAction } from '@wordpress/hooks';

addAction(
	'editor.ErrorBoundary.errorLogged',
	'mu-plugin/error-capture-setup',
	( error ) => {
		// error 是异常的错误对象。
		// 您可以将其输出到控制台或发送到外部错误跟踪工具。
		console.log ( error );
	}
);
```

# 编辑器钩子

WordPress 提供了多个 API，允许您修改编辑器体验。

## 编辑器设置

修改编辑器最常用的方式之一是通过 [`block_editor_settings_all`](https://developer.wordpress.org/reference/hooks/block_editor_settings_all/) PHP 过滤器，该过滤器在设置发送到初始化的编辑器之前应用。这个过滤器允许插件和主题作者对编辑器的行为进行广泛控制。

<div class="callout callout-warning">
	在 WordPress 5.8 之前，这个钩子被称为 <code>block_editor_settings</code>，现已被弃用。如果您需要支持旧版本的 WordPress，可能需要一种检测应使用哪个过滤器的方法。您可以通过检查是否存在在 5.8 版本中引入的 <code>WP_Block_Editor_Context</code> 类来判断 <code>block_editor_settings</code> 是否可以安全使用。
</div>

`block_editor_settings_all` 钩子向回调函数传递两个参数：

- `$settings` – 编辑器可配置设置的数组。
- `$context` – [`WP_Block_Editor_Context`](https://developer.wordpress.org/reference/classes/wp_block_editor_context/) 的实例，该对象包含有关当前编辑器的信息。

以下示例修改了最大上传文件大小。将此代码添加到插件或主题的 `functions.php` 文件中进行测试。

```php
add_filter( 'block_editor_settings_all', 'example_filter_block_editor_settings_when_post_provided', 10, 2 );

function example_filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) {
	if ( ! empty( $editor_context->post ) ) {
		$editor_settings['maxUploadFileSize'] = 12345;
	}
	return $editor_settings;
}
```

编辑器设置有数十种，无法在此文档文章中一一列举，但以下是一些使用 `block_editor_settings_all` 过滤器可以实现的功能示例。

<div class="callout callout-info">
	要查看所有可用的设置，请打开编辑器，然后在浏览器的 <a href="https://developer.wordpress.org/advanced-administration/debug/debug-javascript/#open-the-developer-tools">开发者工具</a> 中打开控制台。输入命令 <code>wp.data.select( 'core/block-editor' ).getSettings()</code> 以显示所有编辑器设置的当前值。
</div>

### 限制代码编辑器访问

`codeEditingEnabled` 默认为 `true`，控制用户是否**除了**可视化编辑器之外还可以访问代码编辑器。在某些情况下，您可能不希望某些用户能够访问此视图。

如果此设置设为 `false`，用户将无法在可视化和代码编辑器之间切换。设置菜单中的选项将不可用，并且切换编辑器类型的键盘快捷键将不会触发。以下是一个示例：

```php
add_filter( 'block_editor_settings_all', 'example_restrict_code_editor' );

function example_restrict_code_editor( $settings ) {
	$can_active_plugins = current_user_can( 'activate_plugins' );

	// 对无法激活插件的用户（非管理员）禁用代码编辑器。
	if ( ! $can_active_plugins ) {
		$settings[ 'codeEditingEnabled' ] = false;
	}

	return $settings;
}
```

### 限制可视化编辑器访问

与 `codeEditingEnabled` 设置类似，`richEditingEnabled` 允许您控制谁可以访问可视化编辑器。如果设为 `true`，用户可以使用可视化编辑器编辑内容。

此设置默认为 [`user_can_richedit`](https://developer.wordpress.org/reference/functions/user_can_richedit/) 函数的返回值。它会检查用户是否可以访问可视化编辑器以及用户的浏览器是否支持它。

### 设置默认图片尺寸

在编辑器中，图片默认设置为 `large` 图片尺寸。您可以使用 `imageDefaultSize` 设置修改此选项，如果您配置了自己的自定义图片尺寸，这将特别有用。以下示例将默认图片尺寸更改为 `medium`。

```php
add_filter( 'block_editor_settings_all', 'example_set_default_image_size' );

function example_set_default_image_size( $settings ) {
	$settings['imageDefaultSize'] = 'medium';
	return $settings;
}
```

### 停用 Openverse

默认情况下，所有 WordPress 站点均启用了 [Openverse](https://openverse.org/) 集成功能，该功能由 `enableOpenverseMediaCategory` 设置项控制。如需停用 Openverse，请应用以下过滤器：

```php
add_filter( 'block_editor_settings_all', 'example_disable_openverse' );

function example_disable_openverse( $settings ) {
	$settings['enableOpenverseMediaCategory'] = false;
	return $settings;
}
```

### 停用字体库

字体库允许用户在站点上安装新字体，该功能默认启用并由 `fontLibraryEnabled` 设置项控制。如需停用字体库，请应用以下过滤器：

```php
add_filter( 'block_editor_settings_all', 'example_disable_font_library' );

function example_disable_font_library( $settings ) {
	$settings['fontLibraryEnabled'] = false;
	return $settings;
}
```

### 停用区块检查器标签页

大多数区块会在检查器中显示[两个标签页](https://make.wordpress.org/core/2023/03/07/introduction-of-block-inspector-tabs/)，一个用于设置，另一个用于样式。您可通过 `blockInspectorTabs` 设置项禁用这些标签页：

```php
add_filter( 'block_editor_settings_all', 'example_disable_inspector_tabs_by_default' );

function example_disable_inspector_tabs_by_default( $settings ) {
	$settings['blockInspectorTabs'] = array( 'default' => false );
	return $settings;
}
```

您还可以调整具体哪些区块启用检查器标签页。以下示例展示了如何为特定区块禁用标签页：

```php
add_filter( 'block_editor_settings_all', 'example_disable_tabs_for_my_custom_block' );

function example_disable_tabs_for_my_custom_block( $settings ) {
	$current_tab_settings = _wp_array_get( $settings, array( 'blockInspectorTabs' ), array() );
	$settings['blockInspectorTabs'] = array_merge(
		$current_tab_settings,
		array( 'my-plugin/my-custom-block' => false )
	);

	return $settings;
}
```

## 区块目录

区块目录允许用户直接在编辑器中从 WordPress.org [插件目录](https://wordpress.org/plugins/browse/block/)安装新的区块插件。您可通过移除加载该功能的操作 `wp_enqueue_editor_block_directory_assets` 来禁用此功能。具体操作如下：

```php
remove_action( 'enqueue_block_editor_assets', 'wp_enqueue_editor_block_directory_assets' );
```

## 区块模式

远程模式（例如来自 WordPress.org [模式目录](https://wordpress.org/patterns/)的模式）默认会在编辑器中向用户开放。此功能由默认值为 `true` 的 `should_load_remote_block_patterns` 参数控制。您可通过将过滤器设置为 false（`__return_false`）来禁用远程模式：

```php
add_filter( 'should_load_remote_block_patterns', '__return_false' );
```

## 编辑器功能

以下过滤器可用于扩展编辑器功能。

### `editor.PostFeaturedImage.imageSize`

此过滤器可用于修改文章特色图片组件中显示的图片尺寸。默认值为 `'post-thumbnail'`，当媒体对象中不存在指定尺寸时，会自动回退到 `full` 原图尺寸。该过滤器仿照经典编辑器中的 `admin_post_thumbnail_size` 过滤器设计。

```js
import { addFilter } from '@wordpress/hooks';

const withImageSize = function ( size, mediaId, postId ) {
	return 'large';
};

addFilter(
	'editor.PostFeaturedImage.imageSize',
	'my-plugin/with-image-size',
	withImageSize
);
```

### `editor.PostPreview.interstitialMarkup`

您还可以过滤生成预览时显示的过渡提示信息。示例如下：

```js
import { addFilter } from '@wordpress/hooks';

const customPreviewMessage = function () {
	return '<b>正在生成文章预览！</b>';
};

addFilter(
	'editor.PostPreview.interstitialMarkup',
	'my-plugin/custom-preview-message',
	customPreviewMessage
);
```