WordPress 核心块库 wordpress/block-library 完全指南批量注册、按需加载与扩展开发【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergwordpress/block-library是 GutenbergWordPress 块编辑器项目中存放全部核心块core blocks的软件包编辑器界面中段落、图片、标题、导航、查询循环等所有内置块都由它提供。本文以该包官方 READMEpackages/block-library/README.md为骨架结合仓库源码深入讲解如何安装并一次性注册全部核心块、如何按需只加载某个块、如何为包新增一个核心块以及块 PHP 代码的命名规范与构建期前缀替换机制帮助你既能在自己项目中正确消费该包也能为 Gutenberg 贡献新块。包概览Block library 是什么该包官方定位是 Block library for the WordPress editor即 WordPress 编辑器的块库。从包元数据packages/block-library/package.json可以看到它的正式名称是wordpress/block-library版本号为11.0.0要求 Node18.12.0、npm8.19.2许可证为 GPL-2.0-or-later。在源码层面包内每个核心块对应src/下的一个目录。从 packages/block-library/src 的目录结构看目前包含约 140 个块覆盖文本类paragraph、heading、verse、quote、媒体类image、gallery、video、audio、file、主题类navigation、query、template-part、site-title、评论区comments、post-comment以及手风琴accordion、标签页tabs等较新的块另有index.jsx作为整个包的聚合入口。每个块目录下通常包含block.json块元数据、index.js注册逻辑、edit.js、save.js、init.js以及对应的.scss样式文件动态块还会带index.phprender_callback。安装与环境要求作为 npm 包安装方式为npm install wordpress/block-library --save包本身是一个 ES2015 模块因此需要你的运行环境支持现代 JavaScript 语法与 API。如果目标环境例如较老的浏览器对 ES2015 特性支持有限官方明确建议引入wordpress/babel-preset-default内置的 polyfill。从 package.json 的导出配置看包同时提供 CommonJS 与 ESM 两种入口main指向build/index.cjsmodule指向build-module/index.mjs此外还开放了./build-module/*、./build-style/*等子路径导出这正是后续按需注册单个块时所依赖的入口。核心 APIregisterCoreBlocksregisterCoreBlocks是包暴露的主 API其官方签名为功能注册由块编辑器提供的全部核心块。参数blocksArray可选——需要注册的核心块数组不传时默认注册全部核心块。最基础用法import { registerCoreBlocks } from wordpress/block-library; registerCoreBlocks();结合 packages/block-library/src/index.jsx 的实现可以看清这个 API 的底层逻辑它远不止“逐个 init”这么简单聚合所有块getAllBlocks()返回一个包含全部块模块的数组其中把paragraph、image、heading、gallery、list、listItem、quote这些常用块放在最前面以便在插入器等上下文优先展示其余块随后按文本、主题、查询、评论等分组排列最后blocks.push( classic )把经典编辑器块freeform追加到末尾并用blocks.filter( Boolean )过滤空值。过滤实验性块__experimentalGetCoreBlocks()调用getAllBlocks().filter( ( { metadata } ) ! isBlockMetadataExperimental( metadata ) )即默认的registerCoreBlocks()只会注册非实验性的块实验性块仅在 Gutenberg 插件环境下通过__experimentalRegisterExperimentalCoreBlocks注册永远不会进入 WordPress 核心详见 is-block-metadata-experimental 的实现逻辑。逐块初始化blocks.forEach( ( { init } ) init() )每个块的init最终调用registerBlockType( { name, ...metadata }, settings )完成注册见 init-block.js。自动注册 PHP 块当存在window.__unstableAutoRegisterBlocks时对每个 PHP-only 块通过私有 APIgetBootstrappedBlockType获取服务端注册的元数据然后registerBlockType生成一个基于useServerSideRender的edit组件、save: () null并强制apiVersion 3、注入postId上下文——这正是 PHP-only 动态块在编辑器中能预览渲染结果的原因。设置全局默认块注册完成后调用setDefaultBlockName( paragraph.name )段落为默认块、setUnregisteredTypeHandlerName( missing.name )未知块处理器、setGroupingBlockName( group.name )分组块若window.wp.oldEditor存在且注册了classic块还会setFreeformContentHandlerName( classic.name )保证经典编辑器块能接管旧内容。按需注册单个块三种加载方式当项目只需要其中一两个块时没必要引入整个包。README 提供了三种粒度递进的做法均以verse诗歌块为例方式一仅当文件被导入时注册import wordpress/block-library/build-module/verse/init;这会触发init.js的副作用块在导入时即被自动注册不返回引用。方式二自动注册并持有块引用import verseBlock from wordpress/block-library/build-module/verse/init;init.js的内容极其简单——import { init } from ./; export default init();见 packages/block-library/src/verse/init.js即导入时完成注册并默认导出注册后的块对象方便后续直接使用其name、settings等属性。方式三完全控制注册时机import { init } from wordpress/block-library/build-module/verse; const verseBlock init();init被手动调用注册时机由你决定例如等待某个用户操作或配置加载完成返回值同样为块对象。从 packages/block-library/src/verse/index.js 可以看到单个块的典型结构从block.json读取name与metadata导出settings含icon、example、transforms、deprecated、merge、edit、save最后export const init () initBlock( { name, metadata, settings } )。而initBlockinit-block.js本质就是一行registerBlockType( { name, ...metadata }, settings )——所谓“注册单个块”最终仍落在wordpress/blocks包的registerBlockType上。以core/verse的 block.json 为例块元数据声明了apiVersion: 3、标题 Poetry、分类textcontent属性为rich-text且__unstablePreserveWhiteSpace: true保留诗歌的空白排版并声明了anchor、color、typography、spacing、interactivity.clientNavigation等 supports 能力——这可以帮助理解“注册一个块”究竟在注册什么。为包新增核心块完整的五步流程README 强调向本包新增块需要额外的步骤不能只写一个目录了事。以新增core/blinking-paragraph为例完整流程如下第 1 步在包的聚合入口登记在 packages/block-library/src/index.jsx 中导入新块模块// packages/block-library/src/index.jsx import * as blinkingParagraph from ./blinking-paragraph;然后把blinkingParagraph加入getAllBlocks()返回的数组中。若该块是实验性的需要在block.json中声明{ __experimental: true }正如前文所述带此标记的块会被isBlockMetadataExperimental过滤默认的registerCoreBlocks不会注册它只有 Gutenberg 插件在“实验”设置开启时才会通过__experimentalRegisterExperimentalCoreBlocks注册见 index.jsx 中按__experimental值筛选的逻辑。第 2 步注册到 PHP 侧在 lib/blocks.php 的gutenberg_reregister_core_block_types()函数中登记新块静态块加入block_folders数组动态块加入block_names数组。该函数会在init钩子上遍历构建产物目录build/scripts/block-library/等中的blocks-manifest.php对每个块先gutenberg_deregister_core_block_and_assets()注销 WordPress 核心同名块及其资源再gutenberg_register_core_block_assets()重新注册插件的样式资源最后有index.php则require_once加载动态块服务端代码否则register_block_type_from_metadata()直接按block.json注册。这样做的意义是插件用自身构建产物替换并升级核心块实现。第 3 步添加init.js在新块目录下创建init.jsimport { init } from ./; export default init();这个文件正是上一节“按需注册单个块”三种方式所依赖的入口。第 4 步声明前端脚本模块script module如果块在前端暴露了脚本模块interactive 脚本必须把它加入包 package.json 的wpScriptModuleExports对象打包进 WordPress 时才会包含它。仓库中实际的例子包括./accordion/view、./image/view、./navigation/view、./query/view、./search/view、./file/view、./playlist/view、./tabs/view等均指向build-module/**/view.mjs。{ name: wordpress/block-library, wpScriptModuleExports: { ./blinking-paragraph/view: ./build-module/blinking-paragraph/view.js, ./image/view: ./build-module/image/view.js // Add any new script modules here. } }每个动态块还需要在自身的render_callback中手动入队enqueue视图脚本模块例如function render_block_core_blinking_paragraph( $attributes, $content ) { $should_load_view_script ! empty( $attributes[isInteractive] ); if ( $should_load_view_script ) { wp_enqueue_script_module( wordpress/block-library/blinking-paragraph ); } return $content; }这一模式在仓库中确有真实用例例如 packages/block-library/src/image/index.php、packages/block-library/src/navigation/index.php、packages/block-library/src/query/index.php 都通过wp_enqueue_script_module( wordpress/block-library/xxx/view )按需加载前端交互脚本。此外 lib/blocks.php 中的gutenberg_defer_block_view_scripts()会遍历所有已注册块类型的view_script_handles通过wp_script_add_data( ..., strategy, defer )为视图脚本统一添加defer加载策略。第 5 步非强制但建议README 提示该包的wpCopyFiles构建配置会复制src/**/*.php与src/*/block.json并在复制 PHP 时执行functionPrefix、classSuffix、prefixFunctions、suffixClasses等变换见 package.json理解这一点有助于把握下面要讲的命名规范。PHP 函数命名规范三个强制前缀包内packages/block-library/src/各子目录中声明的所有 PHP 函数函数名必须以以下前缀之一开头block_core_directory_namerender_block_core_directory_nameregister_block_core_directory_name其中directory_name是 PHP 文件所在目录名目录名统一转为小写除字母和数字外的字符替换为下划线。示例packages/block-library/src/my-block/index.php中声明的函数正确前缀应为block_core_my_blockrender_block_core_my_blockregister_block_core_my_block这一约定使块相关 PHP 函数在代码库中可被快速检索与归属也为将来代码回迁 WordPress 核心Core扫清命名障碍。注意约定仅约束前缀前缀之后的具体函数名可由你自由设计。插件特定前缀何时用、如何用与lib/目录下的 PHP 代码不同那里允许gutenberg_前缀块目录内的 PHP 代码应尽量避免使用gutenberg_这类插件专属前缀或后缀。规则的核心在于块代码最终是要并入 WordPress 核心的插件专属前缀会阻碍回迁。但存在例外当块确实需要调用只在 Gutenberg 插件中才有的函数例如依赖插件特有代码的能力时允许在块 PHP 代码中使用对应的 Corewp_函数并将该函数名加入 package.json 的前缀函数列表。构建时Webpack 会在该列表中查找wp_函数并替换为对应的gutenberg_版本package.json 的wpCopyFiles.transforms.php.prefixFunctions中已列出wp_apply_colors_support、wp_enqueue_block_support_styles、wp_style_engine_get_styles、wp_get_global_styles、wp_get_global_settings等真实条目。替换的前提是除前缀外函数名必须完全一致。例如wp_get_something_useful()会被替换为gutenberg_get_something_useful()。这样设计的效果是插件环境下调用插件增强版的gutenberg_函数当更新回迁到 Core 后块代码仍能调用 Core 的wp_函数两边互不冲突。常见问题与最佳实践小结全量 vs 按需在完整 WordPress 编辑器中直接registerCoreBlocks()即可在自建应用或只使用少量块的场景优先用import wordpress/block-library/build-module/block/init按需加载减小打包体积。实验性块默认不注册不要期望registerCoreBlocks()会带上__experimental: true的块它们只在 Gutenberg 插件实验开关打开时出现。动态块要双端登记JS 侧负责编辑器体验PHP 侧render_callback负责前端渲染与脚本模块入队缺一不可。命名即约定块目录名、block_core_/render_block_core_/register_block_core_前缀、wp_/gutenberg_前缀替换规则共同构成块的“身份”遵循它们才能保证代码可回迁、可维护。如需深入了解块元数据规范、静态块与动态块的区别可继续阅读仓库内的 block API 参考 文档以及本包聚合入口 packages/block-library/src/index.jsx 与 PHP 注册入口 lib/blocks.php 的完整实现。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考