本教程旨在解决wordpress自定义gutenberg区块在编辑器中不显示的问题。核心原因通常是注册区块脚本时使用了错误的文件路径函数，导致前端无法正确加载javascript资源。文章将详细阐述如何正确使用`plugin_dir_url(__file__)`来生成正确的资源url，并提供完整的php和javascript代码示例，确保自定义区块能够顺利在wordpress编辑器中显示和使用。

引言：wordPress自定义Gutenberg区块的构建基础

wordpress Gutenberg编辑器通过区块（Blocks）机制提供了高度模块化的内容创作体验。开发者可以通过自定义区块来扩展编辑器的功能，以满足特定的内容展示需求。一个完整的自定义Gutenberg区块通常由两部分组成：JavaScript前端逻辑（定义区块的编辑界面和保存内容结构）和php后端注册（将JavaScript文件与WordPress系统关联起来）。当自定义区块未能按预期在编辑器中显示时，通常是由于注册过程中某个环节出现问题，其中资源路径的正确性尤为关键。

自定义区块注册流程概述

要使一个自定义区块在WordPress编辑器中可用，需要完成以下主要步骤：

1. 编写JavaScript文件： 使用@wordpress/blocks包提供的registerBlockType函数定义区块的标题、图标、分类、编辑（edit）和保存（save）逻辑。
2. 编译JavaScript文件： 通常使用webpack等工具将ESNext/JSX代码编译为浏览器兼容的JavaScript。此过程还会生成一个asset.php文件，其中包含脚本的依赖项和版本信息。
3. 通过PHP注册区块： 在WordPress的init或enqueue_block_assets钩子中，使用wp_register_script注册JavaScript脚本，然后使用register_block_type函数将脚本与区块ID关联起来。

常见问题与排查思路

当自定义区块未在编辑器中显示时，可以按照以下步骤进行排查：

• 插件/主题激活状态： 确保包含自定义区块代码的插件已激活，或者主题已正确加载。
• 钩子选择： 确认是否在正确的WordPress钩子中注册了区块。通常，init钩子是注册区块的推荐位置，因为它在WordPress加载的早期阶段执行，确保区块在编辑器加载前可用。
• 文件路径验证： 仔细检查所有文件路径是否正确。这包括PHP中引用JavaScript文件和asset.php文件的路径。可以使用error_log()或var_dump()来输出路径，并在WordPress调试日志中查看。
• 浏览器控制台检查： 打开浏览器的开发者工具，检查控制台是否有JavaScript错误或资源加载失败的提示。这是定位前端问题的最直接方法。

核心问题：资源URL的错误引用

在实际开发中，一个非常常见的错误是混淆文件系统路径和Web可访问URL。例如，使用WP_PLUGIN_DIR来获取插件目录的路径是正确的，但它返回的是服务器上的文件系统路径（例如 /var/www/html/wp-content/plugins/your-plugin/），而不是浏览器可以通过http访问的URL（例如 https://yourdomain.com/wp-content/plugins/your-plugin/）。

当使用wp_register_script注册脚本时，WordPress需要的是脚本的Web URL，以便浏览器能够正确地发起HTTP请求来加载该文件。如果提供了文件系统路径，浏览器将无法找到该资源，从而导致区块的JavaScript逻辑无法加载，最终表现为区块在编辑器中不显示。

错误的示例（导致区块不显示）：

AI图像编辑器

使用文本提示编辑、变换和增强照片

46

查看详情

// 假设这是在插件的主文件中 add_action('init', function() {     $asset_file = include( WP_PLUGIN_DIR . '/ghs-custom-blocks/assets/js/landing-page-block.asset.php');      // 错误：wp_register_script需要一个URL，但WP_PLUGIN_DIR提供了文件系统路径     wp_register_script('ghs-landing-page',         WP_PLUGIN_DIR . '/ghs-custom-blocks/assets/js/landing-page-block.js',         $asset_file['dependencies'],         $asset_file['version']);      register_block_type('ghs/landing-page-block', [         'api_version' => 2,         'editor_script' => 'ghs-landing-page',     ]); });

在上述代码中，WP_PLUGIN_DIR . ‘/ghs-custom-blocks/assets/js/landing-page-block.js’生成的是一个文件系统路径，而不是一个HTTP URL。

解决方案：使用正确的URL生成函数

为了解决这个问题，我们需要使用WordPress提供的URL生成函数来获取资源的Web URL。对于插件内的资源，最常用的函数是plugin_dir_url(__FILE__)。这个函数会返回当前插件目录的URL，__FILE__是一个PHP魔术常量，代表当前文件的完整路径。结合__FILE__，plugin_dir_url()能够准确地定位到插件的根URL。

修正后的PHP注册代码：

// 假设此代码位于插件的某个文件中，例如 ghs-custom-blocks/ghs-custom-blocks.php // 或者在插件的某个子文件中，只要 __FILE__ 指向的路径在插件目录内即可  add_action('init', function() {     // 获取插件的URL     $plugin_url = plugin_dir_url(__FILE__);      // 引入asset文件，获取依赖和版本信息     // 注意：这里仍然使用文件系统路径来包含PHP文件     $asset_file = include( plugin_dir_path(__FILE__) . 'assets/js/landing-page-block.asset.php');      // 注册区块脚本，使用正确的Web URL     wp_register_script(         'ghs-landing-page', // 脚本句柄         $plugin_url . 'assets/js/landing-page-block.js', // 脚本的Web URL         $asset_file['dependencies'], // 脚本依赖项         $asset_file['version'], // 脚本版本         true // 在页脚加载脚本     );      // 注册自定义区块     register_block_type('ghs/landing-page-block', [         'api_version' => 2, // 指定API版本         'editor_script' => 'ghs-landing-page', // 关联已注册的脚本句柄         // 'editor_style' => 'ghs-landing-page-editor-style', // 如果有编辑器样式         // 'style' => 'ghs-landing-page-style', // 如果有前端样式     ]); });

JavaScript区块定义代码（无需修改，仅供完整示例）：

import { registerBlockType } from '@wordpress/blocks'  registerBlockType('ghs/landing-page-block', {     title: 'Landing Page', // 区块标题     apiVersion: 2, // API版本     category: 'design', // 区块分类     icon: 'smiley', // 区块图标     description: 'Layout for the GHS landing page', // 区块描述     keywords: ['GHS', 'landing', 'page', 'front'], // 搜索关键词     edit: () => {         // 编辑器中的显示内容         return (<div>hello</div>)     },     save: () => {         // 保存到数据库的内容         return (<div>hello</div>)     } });

注意事项与最佳实践

1. 路径与URL的区分： 始终牢记文件系统路径（如WP_PLUGIN_DIR、plugin_dir_path(__FILE__)）用于服务器端的文件操作（如include、require），而Web URL（如plugin_dir_url(__FILE__)、get_template_directory_uri()）用于浏览器加载资源。
2. __FILE__的上下文： plugin_dir_url(__FILE__)和plugin_dir_path(__FILE__)的准确性取决于__FILE__所在的具体文件位置。如果你的注册代码在一个子目录的文件中，它们将返回该子目录的URL/路径。通常，建议在插件主文件或一个专门的加载文件中使用这些函数。
3. 依赖管理： 现代WordPress区块开发通常使用@wordpress/scripts等工具链，它们会自动生成.asset.php文件，其中包含了区块JavaScript的依赖项和版本。在wp_register_script中使用这些信息是最佳实践，可以确保依赖正确加载并利用缓存。
4. 调试技巧：
   • 浏览器开发者工具： 检查“网络”标签页，看landing-page-block.js是否被请求，以及请求的URL是否正确，状态码是否为200。
   • WordPress调试模式： 在wp-config.php中开启define(‘WP_DEBUG’, true);和define(‘WP_DEBUG_LOG’, true);，通过error_log()输出变量值，然后检查wp-content/debug.log文件。
   • 临时输出： 在PHP代码中，可以暂时使用echo $plugin_url . ‘assets/js/landing-page-block.js’; exit;来直接在浏览器中查看生成的URL。

总结

自定义WordPress Gutenberg区块在编辑器中不显示的问题，往往源于注册区块脚本时对资源路径的错误处理。核心在于区分文件系统路径和Web URL，并使用plugin_dir_url(__FILE__)等正确函数来生成可供浏览器访问的资源URL。通过理解这一关键概念并遵循本文提供的代码示例和排查思路，开发者可以有效解决此类问题，确保自定义区块顺利集成到WordPress编辑器中，提升内容创作的灵活性和效率。

以上就是解决WordPress自定义Gutenberg区块在编辑器中不显示的问题的详细内容，更多请关注php中文网其它相关文章！