Gutenberg 区块插件文件结构详解：create-block 生成的标准目录约定与构建产物映射

Gutenberg 区块插件文件结构详解create-block 生成的标准目录约定与构建产物映射【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本文基于 Gutenberg 仓库的入门文档 File structure of a block完整解析 WordPress 区块插件推荐的文件组织方式从插件主 PHP 文件的注册入口到package.json、src源码目录中每个文件block.json、index.js、edit.js、save.js、样式、render.php、view.js的职责再到build构建目录的产物映射。读完后你将能看懂wordpress/create-block脚手架的每一个生成文件是如何落到仓库源码 packages/create-block 的 Mustache 模板上并理解src到build的编译链路。为什么区块要放在插件里注册开发自定义区块时最佳实践是在插件而非主题中注册区块。这样即使用户切换主题区块依然可用只有少数特殊场景才适合把区块直接内嵌进主题。该指南聚焦于「插件中的区块」并以create-block脚手架工具生成的文件结构为基准遵循这一结构不是强制要求但它是一份可靠的参考能保证区块定义与注册相关文件组织一致、易于维护。插件主文件plugin-file.php服务端注册入口区块的服务端注册发生在插件的主 PHP 文件中并挂载到init钩子上。仓库中 create-block 的插件模板 精确展示了两种注册写法对于基于wp-scripts的项目WordPress 6.8推荐一次性注册blocks-manifest.php中的全部区块function create_block_example_static_block_init() { wp_register_block_types_from_metadata_collection( __DIR__ . /build, __DIR__ . /build/blocks-manifest.php ); } add_action( init, create_block_example_static_block_init );wp_register_block_types_from_metadata_collection()从构建时生成的blocks-manifest.php中读取元数据单次调用即可注册所有区块并顺带注册好各资源使其可在区块编辑器中按需入队。对于更简单的设置或更旧的 WordPress 版本模板提供的是逐区块注册写法见模板 第 59–67 行function create_block_example_static_block_init() { register_block_type( __DIR__ . /build/example-static ); } add_action( init, create_block_example_static_block_init );所有可用的注册方式包括 WordPress 6.7 的wp_register_block_metadata_collection()在 Registration of a block 中有完整说明。插件主文件还需遵循 WordPress 插件头的要求Plugin Name、Version、Text Domain等注释头模板中已生成完整的注释骨架。生成文件的全景结构以create-block的standard模板为例默认值定义在 templates.js 的 getDefaultValues() 中生成后插件大致呈如下结构my-plugin/ ├── my-plugin.php # 插件主文件服务端注册入口 ├── readme.txt # 插件说明 ├── package.json # Node.js 项目配置依赖与开发脚本 ├── src/ │ └── my-block/ │ ├── block.json # 区块元数据构建时随产物复制到 build/ │ ├── index.js # 编辑器端 JS 入口调用 registerBlockType │ ├── edit.js # 编辑器中的 React 渲染组件 │ ├── save.js # 静态区块保存为静态 HTML 的函数 │ ├── style.scss # 编辑器 前端通用样式 │ ├── editor.scss # 仅编辑器生效的样式 │ ├── render.php # 动态区块服务端渲染回调仅动态变体生成 │ └── view.js # 前端前台页面加载的脚本 └── build/ # wp-scripts 构建产物编译、压缩、转译后 ├── blocks-manifest.php # 区块元数据集合--blocks-manifest 时生成 └── my-block/ ├── block.json # 构建后的元数据file:./ 前缀被处理 ├── index.js # 打包后的编辑器脚本 ├── index.css # 由 editor.scss 编译而来 └── style-index.css # 由 style.scss 编译而来需要注意两个源码事实标准模板会把区块放进src/slug/子目录templates.js 中folderName: ./src/$slug便于一个插件容纳多个区块区块分为static静态与dynamic动态两个变体静态变体生成save.js动态变体则改为在block.json中声明render并生成render.php不再生成save.js。package.json区块插件就是一个 Node.js 项目区块插件本质上是一个 Node.js 项目。package.json中定义了区块的npm依赖和本地开发脚本。create-block通过 init-package-json.js 写入该文件并会校验每个依赖是否为可安装的 npm 包。标准模板默认写入三个依赖见 templates.js 第 55–59 行wordpress/block-editor提供useBlockProps等编辑器 APIwordpress/blocks提供registerBlockTypewordpress/i18n提供__()等翻译函数此外还有一个es5模板它不依赖构建流程wpScripts: false、无editorScript适合面向旧环境的简单区块。src目录未编译的源码srcsource目录包含编写区块所用的原始、未编译代码JavaScript、CSS 以及其他资源。你在这里使用现代 JavaScript 特性与 JSX 编写 React 组件。随后wp-scripts提供的构建流程会把这些文件编译为生产可用的文件输出到build目录构建流程详见 JavaScript in the block editor。block.json区块的元数据中枢block.json保存了区块的元数据让区块的定义与注册可以在客户端和服务端之间共享、简化流程。它包含区块名、描述、attributes、supports 等以及指向各功能文件的资源路径。create-block生成block.json的逻辑在 init-block.js 第 36–71 行字段包括$schema、apiVersion、name、version、title、category、icon、description、example、attributes、supports、textdomain以及各资源字段。按standard模板默认值渲染后一份典型block.json如下{ apiVersion: 3, name: create-block/example-static, version: 0.1.0, title: Example Static, category: widgets, icon: smiley, description: Example block scaffolded with Create Block tool., example: {}, supports: { html: false }, textdomain: example-static, editorScript: file:./index.js, editorStyle: file:./index.css, style: file:./style-index.css, viewScript: file:./view.js }$schema字段指向 WordPress 官方 block.json schema URI此处省略链接动态变体会额外携带render: file:./render.php。构建流程应用后block.json与其余生成文件会被移动到build目录因此block.json中的路径最终指向的是编译打包后的版本。其中最重要的几个属性及其默认来源见 templates.js 第 289–291 行属性通常指向构建来源editorScriptbuild/index.js由src/index.js打包默认file:./index.jsstylebuild/style-index.css由src/style.(css\|scss\|sass)编译默认file:./style-index.csseditorStylebuild/index.css由src/editor.(css\|scss\|sass)编译默认file:./index.cssrenderbuild/render.php由src/render.php复制仅动态区块viewScriptbuild/view.js由src/view.js打包默认file:./view.jsindex.js编辑器端入口index.js或block.json中editorScript指定的任何文件是仅在区块编辑器中加载的 JS 入口负责调用registerBlockType在客户端注册区块并导入edit.js与save.js获取注册所需函数。仓库模板 index.js.mustache 渲染后的真实代码import { registerBlockType } from wordpress/blocks; import ./style.scss; import Edit from ./edit; import save from ./save; import metadata from ./block.json; registerBlockType( metadata.name, { edit: Edit, save, } );注意它直接import metadata from ./block.json并以metadata.name作为注册名——客户端注册与服务端共享同一份元数据。模板中还带有注释被引用的style文件会被打包并同时应用到前台与编辑器。edit.js编辑器中的界面组件edit.js包含负责渲染区块编辑界面的 React 组件让用户可以在区块编辑器中交互、自定义区块内容与设置。该组件会传给index.js中registerBlockType的edit属性。模板 edit.js.mustache 的默认实现import { __ } from wordpress/i18n; import { useBlockProps } from wordpress/block-editor; import ./editor.scss; export default function Edit() { return ( p { ...useBlockProps() } { __( Example Static – hello from the editor!, example-static ) } /p ); }其中useBlockProps()会返回区块包裹元素所需的类名等 propseditor.scss在此处导入即编辑器专用样式随该入口打包。save.js写入数据库的静态标记save.js导出一个函数返回要保存到 WordPress 数据库的静态 HTML 标记传给index.js中registerBlockType的save属性见 block edit/save 参考。模板实现import { useBlockProps } from wordpress/block-editor; export default function save() { return ( p { ...useBlockProps.save() } { Example Static – hello from the saved content! } /p ); }只有静态区块生成save.js动态区块把前端渲染交给服务端的render.php因此不输出该文件。style.(css|scss|sass)与editor.(css|scss|sass)双端与单端样式style文件.css/.scss/.sass包含区块在编辑器与前端都会加载的样式。构建过程中它被编译为style-index.css通常通过block.json的style属性声明。wp-scripts内部 webpack 配置串联了 css-loader、postcss-loader 与 sass-loader因此可以处理 CSS、SASS 或 SCSS 文件。editor文件.css/.scss/.sass包含仅区块编辑器中生效的附加样式常用来写区块 UI 专属的样式。它在构建时被编译为index.css通常通过editorStyle属性声明。render.php动态区块的服务端渲染render.php或render属性指向的任何文件定义了前端请求区块时服务端返回标记的过程。若定义了该文件它将优先于其他前端渲染方式。动态变体模板 render.php.mustache 展示了服务端可用变量$attributes区块属性、$content默认内容、$blockWP_Block实例p ?php echo get_block_wrapper_attributes(); ? ?php esc_html_e( Example Dynamic – hello from a dynamic block!, example-static ); ? /pview.js前台脚本view.js或viewScript属性指向的文件会在区块显示的前台页面中加载。标准模板默认就声明了viewScript: file:./view.js模板文件本身只有一个console.log示例并明确提醒如果你的区块不需要前端 JS应删除该文件并从block.json移除viewScript属性。build目录WordPress 真正入队的产物build目录包含src中代码的编译与优化版本由wp-scripts的build或start命令触发生成。转换过程包括压缩minification、把现代 JavaScript 转译为兼容更多浏览器的版本、以及资源打包以高效加载。WordPress 最终入队使用的是build目录的内容并在区块编辑器与前端渲染区块。与注册配套的blocks-manifest.php由wp-scripts build-blocks-manifest命令生成或给build/start命令加--blocks-manifest标志它把项目中所有block.json的元数据编译进单个 PHP 文件这正是插件主文件中wp_register_block_types_from_metadata_collection()的读取来源需要 WordPress 6.8。另外wp-scripts构建命令还支持webpack-src-dir与output-path选项可以自定义入口与输出目录。生成后的常用命令create-block脚手架在生成完成后会直接提示可用命令见 scaffold.js 第 226–254 行$ npm start # 启动开发构建监听模式 $ npm run build # 构建生产代码 $ npm run format # 格式化文件 $ npm run lint:css # 检查 CSS $ npm run lint:js # 检查 JS $ npm run plugin-zip # 生成可上传的插件 zip 包 $ npm run packages-update # 更新 WordPress 包到最新版本小结与延伸阅读一份规范的区块插件 插件主 PHP服务端注册package.json依赖与脚本srcblock.json元数据、index.js/edit.js/save.js、双端样式、render.php/view.jsbuildWordPress 实际加载的产物。这一结构在仓库中的完整实现见 packages/create-block 的模板与脚手架代码。相关深入文档Registration of a block服务端/客户端注册的全部方式Block metadatablock.json各字段参考Block edit/saveedit与save的语义JavaScript in the block editor构建流程细节【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考