区块编辑器钩子


钩子是 WordPress 的基础功能之一。它们允许你“钩入”WordPress 核心,并在 WordPress 生命周期中的特定时间点执行自己的代码。

区块编辑器有自己的一组钩子,允许你与编辑器交互并修改其行为。

本课程将介绍区块编辑器中可用的一些不同钩子,以及如何使用它们来扩展编辑器的功能。

@wordpress/hooks 包

虽然操作和筛选器钩子历来仅在 PHP 中可用,但由于区块编辑器是使用 JavaScript 构建的,现在也有了一组新的 JavaScript 钩子。

这些 JavaScript 操作和筛选器钩子允许你钩入编辑器的不同方面,并更改编辑器的行为或区块本身。

JavaScript 钩子使用 addActionaddFilter 函数进行注册,这些函数来自 @wordpress/hooks

与 PHP 版本类似,你需要将钩子名称和回调函数传递给这些函数。

一个值得注意的区别是,你还必须传递钩子的命名空间。命名空间是回调函数的唯一标识符,有助于避免命名冲突。

让我们看一个示例,演示如何使用 JavaScript 钩子。

blocks.registerBlockType 筛选器

对于目前为止所看到的所有区块示例,你都使用了来自 @wordpress/blocks 包的 registerBlockType 函数,在 JavaScript 中注册区块。

每个区块都首先使用此函数注册一个新的区块类型定义。

/**
 * Every block starts by registering a new block type definition.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
 */
registerBlockType( metadata.name, {
    /**
     * @see ./edit.js
     */
    edit: Edit,

    /**
     * @see ./save.js
     */
    save,
} );

处理所有已注册区块的代码运行时,所有挂接到 blocks.registerBlockType 筛选器钩子中的回调函数都会运行,并且应返回修改后的区块设置对象。

    const settings = applyFilters(
        'blocks.registerBlockType',
        blockType,
        name,
        null
    );

此筛选器钩子允许你在注册区块之前修改区块设置对象。

要向 blocks.registerBlockType 筛选器注册回调函数,需要使用来自 @wordpress/hooks 包的 addFilter 函数。

让我们创建一个插件来加入 JavaScript 文件,以注册此筛选器。

首先,在你的 wp-content/plugins 目录中创建一个目录,用于存放区块钩子代码。

mkdir -p wp-content/plugins/wp-learn-block-hooks

在新创建的目录中创建主插件 PHP 文件 wp-learn-block-hooks.php

然后添加以下代码来设置插件头信息,并确保插件代码仅在 WordPress 环境中运行:

<?php
/**
 * Plugin Name:       WP Learn Block Hooks
 * Description:       WP Learn Block Hooks
 * Requires at least: 6.6
 * Requires PHP:      7.0
 * Version:           1.0.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       wp-learn-block-hooks
 *
 */
if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

接下来,你可以将回调函数挂接到 enqueue_block_editor_assets 操作,以加入 JavaScript 文件。

add_action( 'enqueue_block_editor_assets', 'wp_learn_block_hooks_editor_assets' );
function wp_learn_block_hooks_editor_assets() {
    wp_enqueue_script(
        'wp-learn-block-hooks-editor-script',
        plugin_dir_url( __FILE__ ) . 'block-hooks.js',
        array(
            'wp-hooks',
        ),
    );
}

注意,你需要指定 wp-hooks 依赖项,以确保区块钩子代码仅在 @wordpress/hooks 包可用后加载。这是因为你将在 JavaScript 文件中使用来自 @wordpress/hooks 包的 addFilter 函数。

现在,在插件目录中创建一个 block-hooks.js 文件,并以 IIFE(立即调用函数表达式)开始,以防止此代码中的任何变量泄漏到全局作用域:

( function(){

} )()

接下来,使用 addFilter 函数,在 blocks.registerBlockType 筛选器钩子上注册一个回调:

( function(){
    wp.hooks.addFilter(
        'blocks.registerBlockType',
        'wp-learn-block-hooks/list-block-description',
        addListBlockDescription
    );
} )()

注意,在回调函数 addListBlockDescription 之前指定了一个唯一的命名空间。命名空间由开发者定义,并且应该在你的插件中保持唯一。

现在,让我们创建 addListBlockDescription 回调函数来执行一些操作:

    function addListBlockDescription( settings, name ) {
        if ( name === 'core/list' ) {
            settings.description = 'This is a list block';
        }
        return settings;
    }

在这里,addListBlockDescription 回调函数接收区块的设置对象和区块名称作为参数。

然后,它会检查正在注册的区块是否为列表区块;如果是,则更改区块设置对象的 description 属性。

最后,由于这是一个筛选器,它需要返回某些内容;在本例中,需要返回修改后的设置对象。

要测试此功能,请暂时不要激活插件,而是编辑一篇文章或页面,并从区块插入器中搜索列表区块。

将鼠标悬停在列表区块上时,你应该会看到显示的描述“创建项目符号列表或编号列表”。

现在,激活插件。

激活插件后,你应该会看到列表区块的描述变为“这是一个列表区块”。

区块编辑器钩子文档

区块编辑器手册有一个专门介绍区块编辑器钩子的部分,其中包含不同类型钩子对应的不同页面。

区块筛选器页面列出了所有可用的筛选器,这些筛选器允许你修改现有区块的行为,其中包括在区块注册期间修改区块、在前端修改区块、改变区块在区块编辑器中的行为、移除区块、隐藏区块以及管理区块分类。

编辑器钩子记录了所有允许你修改编辑器体验的钩子,包括修改编辑器设置、禁用区块目录和样式目录功能、扩展编辑器功能、控制编辑器的 REST API 数据以及记录编辑器错误。

国际化筛选器页面列出了允许你修改编辑器中所使用国际化函数的筛选器。

解析器筛选器记录了所有允许你修改区块解析器的筛选器。区块解析器用于将存储在内存中的区块数据转换为存储在数据库文章内容中的区块标记。

自动完成是 @wordpress/block-editor 包中的一个组件,用于向编辑器添加自动完成器。

如果你曾在区块编辑器中使用过 @username 功能,那么该功能就是由自动完成组件提供支持的。

自动完成筛选器页面记录了如何向编辑器添加你自己的自动完成器。

最后,全局样式筛选器页面记录了 WordPress 6.1 中添加的筛选器,这些筛选器允许开发者修改由 theme.json 文件定义的区块主题全局设置和样式。

所有这些页面都包含有关如何使用这些钩子,以及如何利用它们扩展区块编辑器功能的详细示例。