解析 WordPress `gutenberg_enqueue_block_editor_assets()` 函数的源码：如何加载区块编辑器所需的资源。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，晚上好！我是今天的讲师，咱们今儿个聊聊 WordPress 里边那个负责给区块编辑器（Gutenberg）装扮门面的大管家——gutenberg_enqueue_block_editor_assets() 函数。别看名字挺长，其实干的活儿就是把区块编辑器所需的各种宝贝（JS，CSS等等）都安排到位，让它能正常工作。

准备好了吗？咱们这就开始这场代码探险！

一、开门见山：函数概览

首先，我们先来瞅瞅这个函数的庐山真面目。虽然我们不能直接看到 WordPress 核心代码的源码（因为它散落在多个文件中，而且版本不同可能会有差异），但是我们可以根据 WordPress 的文档和相关代码片段来理解它的功能。

简单来说，gutenberg_enqueue_block_editor_assets() 的主要职责就是：

注册并加载 JavaScript 脚本： 包括区块编辑器的核心代码、各种区块的 JavaScript 代码、以及其他必要的依赖脚本。
注册并加载 CSS 样式： 包括区块编辑器的基础样式、各种区块的样式、以及其他必要的样式表。
本地化脚本： 将一些 PHP 变量传递给 JavaScript 代码，比如一些配置信息、翻译文本等等。

二、深入虎穴：代码结构分析（模拟源码）

由于我们不能直接拿到 WordPress 核心代码，所以这里我模拟一个 gutenberg_enqueue_block_editor_assets() 函数的简化版，让大家更直观地了解它的工作流程。

<?php
/**
 * 模拟 gutenberg_enqueue_block_editor_assets 函数
 */
function my_gutenberg_enqueue_block_editor_assets() {

  // 1. 注册区块编辑器核心脚本
  wp_register_script(
    'my-gutenberg-editor', // 脚本句柄 (handle)
    plugins_url( 'assets/js/editor.js', __FILE__ ), // 脚本路径
    array( 'wp-blocks', 'wp-element', 'wp-i18n', 'wp-editor' ), // 依赖
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/js/editor.js' ), // 版本号 (根据文件修改时间)
    true // 在 footer 加载
  );

  // 2. 注册区块编辑器核心样式
  wp_register_style(
    'my-gutenberg-editor', // 样式句柄
    plugins_url( 'assets/css/editor.css', __FILE__ ), // 样式路径
    array( 'wp-edit-blocks' ), // 依赖
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/css/editor.css' ) // 版本号
  );

  // 3. 注册自定义区块脚本 (例如：一个叫做 'my-block' 的区块)
  wp_register_script(
    'my-block',
    plugins_url( 'assets/js/my-block.js', __FILE__ ),
    array( 'wp-blocks', 'wp-element', 'wp-editor' ),
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/js/my-block.js' )
  );

  // 4. 注册自定义区块样式 (例如：一个叫做 'my-block' 的区块)
  wp_register_style(
    'my-block',
    plugins_url( 'assets/css/my-block.css', __FILE__ ),
    array( 'wp-edit-blocks' ),
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/css/my-block.css' )
  );

  // 5. 本地化脚本 (将 PHP 数据传递给 JavaScript)
  wp_localize_script(
    'my-gutenberg-editor', // 脚本句柄
    'myGutenbergData', // JavaScript 对象名
    array(
      'api_url' => rest_url( 'my-plugin/v1' ), // REST API 地址
      'nonce' => wp_create_nonce( 'wp_rest' ) // 安全 nonce
    )
  );

  // 6. 加载脚本和样式
  wp_enqueue_script( 'my-gutenberg-editor' );
  wp_enqueue_style( 'my-gutenberg-editor' );

  // 7. 加载自定义区块的脚本和样式 (根据需要)
  wp_enqueue_script( 'my-block' );
  wp_enqueue_style( 'my-block' );
}

// 将函数挂载到 'enqueue_block_editor_assets' 钩子上
add_action( 'enqueue_block_editor_assets', 'my_gutenberg_enqueue_block_editor_assets' );

代码解释：

wp_register_script() 和 wp_register_style()： 这两个函数是 WordPress 提供用于注册 JavaScript 脚本和 CSS 样式表的。注册的意思是告诉 WordPress "嘿，这里有个脚本/样式，你先记着，啥时候需要用再加载"。
- 句柄 (handle)： 每个脚本和样式都有一个唯一的句柄，方便 WordPress 管理。
- 路径 (path)： 指向脚本或样式文件的 URL。 plugins_url() 函数可以方便地获取插件目录下的文件 URL。
- 依赖 (dependencies)： 指定当前脚本或样式依赖的其他脚本或样式。 WordPress 会确保依赖项先被加载。比如，'wp-blocks'、'wp-element'、'wp-i18n'、'wp-editor' 和 'wp-edit-blocks' 都是 WordPress 内置的，区块编辑器需要用到的核心库。
- 版本号 (version)： 用于缓存控制。通常使用文件修改时间作为版本号，这样每次文件修改后，浏览器都会重新加载。
- in_footer (仅 wp_register_script() 适用)： 指定脚本是否在 <footer> 中加载。通常设置为 true，以提高页面加载速度。
wp_localize_script()： 这个函数允许你将 PHP 数据传递给 JavaScript 代码。
- 脚本句柄： 要本地化的脚本的句柄。
- JavaScript 对象名： JavaScript 中用于访问数据的对象名。比如，这里我们创建了一个名为 myGutenbergData 的 JavaScript 对象。
- 数据数组： 要传递给 JavaScript 的数据。数据会转换成 JavaScript 对象。
wp_enqueue_script() 和 wp_enqueue_style()： 这两个函数用于实际加载注册过的脚本和样式。加载的意思是告诉 WordPress "嘿，把这个脚本/样式给我加载到页面上"。
add_action( 'enqueue_block_editor_assets', 'my_gutenberg_enqueue_block_editor_assets' )： 这行代码将我们的函数挂载到 enqueue_block_editor_assets 钩子上。这意味着当 WordPress 准备加载区块编辑器的资源时，就会自动调用我们的函数。

三、庖丁解牛：关键函数详解

接下来，我们详细分析一下上面代码中用到的几个关键函数：

函数名	作用
`wp_register_script()`	注册一个 JavaScript 脚本。告诉 WordPress 这个脚本的存在，以及它的路径、依赖、版本号等信息。
`wp_register_style()`	注册一个 CSS 样式表。告诉 WordPress 这个样式表的存在，以及它的路径、依赖、版本号等信息。
`wp_enqueue_script()`	加载一个 JavaScript 脚本。将注册过的脚本添加到页面中。
`wp_enqueue_style()`	加载一个 CSS 样式表。将注册过的样式表添加到页面中。
`wp_localize_script()`	将 PHP 数据传递给 JavaScript 脚本。创建一个 JavaScript 对象，其中包含从 PHP 传递过来的数据。这对于将配置信息、翻译文本等传递给 JavaScript 代码非常有用。
`plugins_url()`	获取插件目录下的文件的 URL。方便地构建脚本和样式文件的路径。
`filemtime()`	获取文件的最后修改时间。用于生成版本号，确保浏览器在文件修改后重新加载。
`add_action()`	将一个函数挂载到一个 WordPress 钩子上。当 WordPress 触发该钩子时，会自动调用挂载的函数。 `enqueue_block_editor_assets` 钩子在区块编辑器加载资源时触发。

四、实战演练：自定义区块资源的加载

假设我们要创建一个自定义区块，叫做 "My Awesome Block"，它需要自己的 JavaScript 和 CSS 文件。我们可以按照以下步骤来加载这些资源：

创建 JavaScript 文件 (assets/js/my-awesome-block.js)：

( function( blocks, element ) {
  var el = element.createElement;

  blocks.registerBlockType( 'my-plugin/my-awesome-block', {
    title: 'My Awesome Block',
    icon: 'smiley',
    category: 'common',
    edit: function() {
      return el( 'p', {}, 'Hello from My Awesome Block!' );
    },
    save: function() {
      return el( 'p', {}, 'Hello from My Awesome Block!' );
    }
  } );
} )( wp.blocks, wp.element );

创建 CSS 文件 (assets/css/my-awesome-block.css)：

.wp-block-my-plugin-my-awesome-block {
  background-color: #f0f0f0;
  padding: 20px;
  border: 1px solid #ccc;
}

在 my_gutenberg_enqueue_block_editor_assets() 函数中注册和加载资源：

<?php
/**
 * 模拟 gutenberg_enqueue_block_editor_assets 函数
 */
function my_gutenberg_enqueue_block_editor_assets() {

  // 1. 注册区块编辑器核心脚本
  wp_register_script(
    'my-gutenberg-editor', // 脚本句柄 (handle)
    plugins_url( 'assets/js/editor.js', __FILE__ ), // 脚本路径
    array( 'wp-blocks', 'wp-element', 'wp-i18n', 'wp-editor' ), // 依赖
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/js/editor.js' ), // 版本号 (根据文件修改时间)
    true // 在 footer 加载
  );

  // 2. 注册区块编辑器核心样式
  wp_register_style(
    'my-gutenberg-editor', // 样式句柄
    plugins_url( 'assets/css/editor.css', __FILE__ ), // 样式路径
    array( 'wp-edit-blocks' ), // 依赖
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/css/editor.css' ) // 版本号
  );

  // 3. 注册自定义区块脚本 (My Awesome Block)
  wp_register_script(
    'my-awesome-block',
    plugins_url( 'assets/js/my-awesome-block.js', __FILE__ ),
    array( 'wp-blocks', 'wp-element', 'wp-editor' ),
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/js/my-awesome-block.js' )
  );

  // 4. 注册自定义区块样式 (My Awesome Block)
  wp_register_style(
    'my-awesome-block',
    plugins_url( 'assets/css/my-awesome-block.css', __FILE__ ),
    array( 'wp-edit-blocks' ),
    filemtime( plugin_dir_path( __FILE__ ) . 'assets/css/my-awesome-block.css' )
  );

  // 5. 本地化脚本 (将 PHP 数据传递给 JavaScript)
  wp_localize_script(
    'my-gutenberg-editor', // 脚本句柄
    'myGutenbergData', // JavaScript 对象名
    array(
      'api_url' => rest_url( 'my-plugin/v1' ), // REST API 地址
      'nonce' => wp_create_nonce( 'wp_rest' ) // 安全 nonce
    )
  );

  // 6. 加载脚本和样式
  wp_enqueue_script( 'my-gutenberg-editor' );
  wp_enqueue_style( 'my-gutenberg-editor' );

  // 7. 加载自定义区块的脚本和样式 (My Awesome Block)
  wp_enqueue_script( 'my-awesome-block' );
  wp_enqueue_style( 'my-awesome-block' );
}

// 将函数挂载到 'enqueue_block_editor_assets' 钩子上
add_action( 'enqueue_block_editor_assets', 'my_gutenberg_enqueue_block_editor_assets' );

注意： 将 my-plugin 替换成你的插件名称。

五、注意事项与常见问题

依赖关系： 确保正确指定脚本和样式的依赖关系。如果依赖关系不正确，可能会导致 JavaScript 错误或样式表加载顺序错误。通常，自定义区块的 JavaScript 代码需要依赖 wp-blocks、wp-element 和 wp-editor。自定义区块的样式需要依赖 wp-edit-blocks。
版本号： 使用文件修改时间作为版本号可以确保浏览器在文件修改后重新加载。这对于开发过程中调试非常有用。
加载位置： 通常将 JavaScript 脚本放在 <footer> 中加载，以提高页面加载速度。可以通过将 wp_register_script() 函数的第五个参数设置为 true 来实现。
缓存： 浏览器和服务器可能会缓存脚本和样式表。如果在修改了脚本或样式表后，浏览器仍然加载旧版本，可以尝试清除浏览器缓存或使用不同的版本号。
冲突： 如果多个插件或主题都注册了相同句柄的脚本或样式，可能会发生冲突。为了避免冲突，建议使用唯一的句柄。
调试： 使用浏览器的开发者工具可以帮助你调试 JavaScript 错误和 CSS 样式问题。

六、总结

gutenberg_enqueue_block_editor_assets() 函数是 WordPress 区块编辑器资源加载的核心。通过注册和加载 JavaScript 脚本和 CSS 样式表，它可以确保区块编辑器能够正常工作。理解这个函数的工作原理对于开发自定义区块和扩展区块编辑器的功能至关重要。

希望今天的讲座对大家有所帮助。下次再见！

发表回复 取消回复

发表回复取消回复