使用 JavaScript 与区块编辑器协作

最后更新：2026-10-17 10:55:29

为区块编辑器开发区块通常涉及使用现代 JavaScript（ESNext 和 JSX），此处区块编辑器手册中的大多数示例均使用这些语法编写。

然而，这种形式的 JavaScript 必须转换为浏览器兼容的格式，因此需要构建步骤。此过程将 JavaScript 源代码及相关资源转换为适合生产环境的格式。

带构建过程的 JavaScript

为区块开发使用构建过程可以释放现代 JavaScript 的全部潜力，从而促进使用 ESNext 和 JSX。

ESNext 指 JavaScript 的最新语法和功能。JSX 是由 React 项目开发的语法扩展，使您能够编写类似 HTML 的 JavaScript。

由于浏览器无法直接执行 ESNext 和 JSX，因此必须将这些语法转换为浏览器兼容的 JavaScript。

webpack 是一个可插拔工具，用于处理并为浏览器兼容性打包 JavaScript。Babel 是 webpack 的一个插件，可将 ESNext 和 JSX 转换为标准 JavaScript。

配置 webpack 和 Babel 可能具有挑战性，因此建议使用 @wordpress/scripts 包。此工具通过预先配置两者来简化开发，因此您很少需要编写自定义的 webpack 或 Babel 配置。

作为入门介绍，请参阅使用 wp-scripts 入门指南。

wp-scripts 概述

下图提供了使用 wp-scripts 包时的构建过程概述。它旨在与开发环境和生产环境的标准配置开箱即用。

生产模式 (npm run build)： 在此模式下，wp-scripts 编译您的 JavaScript，压缩输出以减少文件大小并提高浏览器中的加载时间。这对于将代码部署到实时站点非常理想。
开发模式 (npm start)： 此模式专为积极开发量身定制。它跳过压缩以便于调试，生成源地图以更好地跟踪错误，并监视您的源文件以查找更改。当检测到更改时，它会自动重新构建受影响的文件，使您能够实时查看更新。

wp-scripts 包还促进使用 JavaScript 模块，允许代码分布在多个文件中，并在构建过程后产生精简的捆绑包。block-development-example GitHub 仓库提供了一些很好的示例。

在大多数情况下，不需要自定义，但在使用 wp-scripts 时，您可以提供 webpack.config.js 来修改构建过程以适应您的需求。

不带构建过程的 JavaScript

在特定场景中，在不使用构建过程的情况下将 JavaScript 集成到您的 WordPress 项目中可能是最直接的方法。这对于不利用 JSX 或其他需要编译的高级 JavaScript 功能的项目尤其如此。

当您选择不使用构建过程时，您通过全局 wp 对象直接与 WordPress 的JavaScript API交互。这意味着 WordPress 提供的所有方法和包都立即可用，但有一个注意事项：您必须手动管理脚本依赖项。这是通过将每个相应包的句柄添加到您的挂起 JavaScript 文件的依赖数组中来实现的。

例如，假设您正在创建一个使用 registerBlockVariation 函数（来自 blocks 包）注册新区块变体的脚本。您必须在脚本的依赖数组中包含 wp-blocks。这保证在您的脚本执行时，wp.blocks.registerBlockVariation 方法可用且已定义。

在以下示例中，当挂起 variations.js 文件时定义了 wp-blocks 依赖项。

function example_enqueue_block_variations() {
    wp_enqueue_script(
        'example-enqueue-block-variations',
        get_template_directory_uri() . '/assets/js/variations.js',
        array( 'wp-blocks' ),
        wp_get_theme()->get( 'Version' ),
        false
    );
}
add_action( 'enqueue_block_editor_assets', 'example_enqueue_block_variations' );

然后在 variations.js 文件中，您可以像这样为媒体和文本区块注册新变体：

wp.blocks.registerBlockVariation(
    'core/media-text',
    {
        name: 'media-text-custom',
        title: 'Media & Text Custom',
        attributes: {
            align: 'wide',
            backgroundColor: 'tertiary'
        },
    }
);

对于需要在区块编辑器中运行的脚本，请确保使用 enqueue_block_editor_assets 钩子与标准 wp_enqueue_script 函数配合使用。

有关更多信息，请参阅在编辑器中挂起资源。

打开浏览器的开发工具，并在编辑帖子或使用站点编辑器时在控制台运行 wp.data.select('core/editor').getBlocks()。此命令将返回所有可用的区块。

使用 JavaScript 与区块编辑器协作

带构建过程的 JavaScript

wp-scripts 概述

不带构建过程的 JavaScript

其他资源