WordPress 块编辑器Gutenberg块模板Block Template机制详解注册、嵌套与锁定的完整参考【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg块模板Block Template是 GutenbergWordPress 块编辑器项目中用于定义编辑器会话初始状态的核心机制。本文基于仓库参考文档 block-templates.md 展开完整覆盖模板的定义语法、在 PHP 与 JavaScript 中的两种注册方式、自定义文章类型的模板绑定、模板级与块级锁定Locking的全部选项以及嵌套模板的写法并结合仓库源码指出各机制对应的实现与配置位置帮助开发者为任意文章类型或容器块定制开箱即用的编辑器初始结构。一、什么是块模板块模板被定义为一个块项列表a list of block items。列表中的每个块可以拥有预定义属性predefined attributes占位内容placeholder content静态或动态dynamic内容。块模板的价值在于它允许开发者为一次编辑器会话指定默认的初始状态从而让编辑者在打开某类内容时直接面对一组结构化的块而不是空白画布。模板的作用范围scope包括在客户端动态设置默认状态例如defaultBlock注册为给定文章类型post type的默认模板。仓库文档同时记录了规划中的扩展方向planned additions可帮助理解模板体系的设计演进保存为“页面模板”page templates并分配给页面在template.php文件中定义或从站点专属的自定义文章类型wp_templates中读取作为主题层级theme hierarchy的等价物。二、API模板在 JS 或 PHP 中声明模板可以在 JavaScript 或 PHP 中声明形式均为块类型数组block name 可选 attributes。2.1 PHP为文章post注册模板下面的 PHP 示例为post文章类型创建一个模板编辑器打开时首屏包含一个图像块——模板中可以加入任意数量的块?php function myplugin_register_template() { $post_type_object get_post_type_object( post ); $post_type_object-template array( array( core/image ), ); } add_action( init, myplugin_register_template );要点在init钩子中取得目标文章类型的对象把模板数组赋给其template属性。数组的每一项是一个内层数组第一项为块名第二项可选为该块的属性字典。2.2 JavaScript在块的编辑函数中使用模板JavaScript 示例展示了一个使用 InnerBlocks 组件注册新块的完整例子。该块在插入编辑器时会依据模板生成一组子块const el React.createElement; const { registerBlockType } wp.blocks; const { InnerBlocks } wp.blockEditor; const BLOCKS_TEMPLATE [ [ core/image, {} ], [ core/paragraph, { placeholder: Image Details } ], ]; registerBlockType( myplugin/template, { title: My Template Block, category: widgets, edit: ( props ) { return el( InnerBlocks, { template: BLOCKS_TEMPLATE, templateLock: false, } ); }, save: ( props ) { return el( InnerBlocks.Content, {} ); }, } );从代码结构看edit中通过InnerBlocks的template属性传入模板数组save中则使用InnerBlocks.Content将子块序列化进标记templateLock: false表示该区域内不做锁定用户可自由增删改子块。仓库文档同时建议参考 Meta Box 教程 中模板实际使用in use的完整示例。三、模板中可定义的块属性要为模板中的块指定哪些属性权威依据是该块的block.json文件重点查看attributes与supports两个字段。以标题块为例packages/block-library/src/heading/block.json 中定义了level等属性并通过supports声明对anchor参数的支持——因此模板中既可为标题块设置level相关属性也可使用锚点anchor参数。如果服务器未安装 Gutenberg 插件block.json文件位于 WordPress 核心目录wp-includes/blocks/heading/block.json以对应核心版本的实际内容为准。四、自定义文章类型注册模板自定义文章类型CPT可以在注册时直接携带template参数。以下示例注册了一个book文章类型并为其绑定一个“封面图 作者标题 描述段落”的初始模板function myplugin_register_book_post_type() { $args array( public true, label Books, show_in_rest true, template array( array( core/image, array( align left, ) ), array( core/heading, array( placeholder Add Author..., ) ), array( core/paragraph, array( placeholder Add Description..., ) ), ), ); register_post_type( book, $args ); } add_action( init, myplugin_register_book_post_type );注意show_in_rest true是块编辑器可用的前提template数组中的每一项展示了属性写法的常见组合core/image使用align属性对齐方式core/heading与core/paragraph使用placeholder属性占位提示文本。五、模板级锁定Locking当希望“模板给出的块不可被操作”时可使用template_lock属性对整个模板加锁function myplugin_register_template() { $post_type_object get_post_type_object( post ); $post_type_object-template array( array( core/paragraph, array( placeholder Add Description..., ) ), ); $post_type_object-template_lock all; } add_action( init, myplugin_register_template );锁定的可选值以仓库文档给出的说明为准contentOnly—— 阻止所有操作此外不具备内容content的块类型会从列表视图中隐藏且无法在块列表中获取焦点。与其余锁定类型不同该锁定不能被子级覆盖not overridable by children。all—— 阻止所有操作不能插入新块、不能移动现有块、不能删除块。insert—— 阻止插入或删除块但允许移动现有块。锁定的继承规则值得注意锁定设置可被 InnerBlocks 继承。若某个 InnerBlocks 区域未设置templateLock则沿用其父级 InnerBlocks 区域的锁定若块是顶层块则采用当前文章类型的锁定配置即template_lock。六、单个块的锁定Individual block locking除模板级锁定外还可以用属性层attributes level的lock属性锁定单个块。块级锁定的优先级高于templateLock。目前支持锁定块的移动moving与删除removingattributes: { // Prevent a block from being moved or removed. lock: { remove: true, move: true, } }选项说明remove—— 锁定块被删除的能力move—— 锁定块被移动的能力。配合templateLock可以实现“全部锁定、唯独放行一个块”的效果在整体锁定状态下对特定块的remove或move显式写false即可解除该块的对应锁定$template array( array( core/image, array( align left, ) ), array( core/heading, array( placeholder Add Author..., ) ), // Allow a Paragraph block to be moved or removed. array( core/paragraph, array( placeholder Add Description..., lock array( move false, remove false, ), ) ), );在仓库源码中与锁定语义对应的 API 位于 packages/blocks/src/lock-unlock.ts其中的lock/unlock通过wordpress/private-apis的__dangerousOptInToUnstableAPIsOnlyForCoreModules导出——从源码结构看这属于核心内部使用的私有接口文档中也提示私有 API 的稳定性边界详见 private-apis.md普通主题与插件应通过上文所述的模板 / 属性声明方式template_lock、lock属性来控制锁定行为而非直接调用这些内部函数。七、嵌套模板Nested templates列columns等容器块同样支持模板给容器块分配一个嵌套模板即可。数组写法为[ 块名, 属性, 子模板数组 ]——第三项即该块内部的子模板$template array( array( core/paragraph, array( placeholder Add a root-level paragraph, ) ), array( core/columns, array(), array( array( core/column, array(), array( array( core/image, array() ), ) ), array( core/column, array(), array( array( core/paragraph, array( placeholder Add an inner paragraph ) ), ) ), ) ) );结构解读根级先放一个段落块接着是core/columns容器块属性为空数组其第三项数组包含两个core/column子块每个列内部再各自携带模板——左列一个core/image右列一个带占位文本的core/paragraph。这种“块名 属性 子模板”的三元组形式可以无限递归从而用一份模板数组描述任意深度的块树结构。八、小结与延伸阅读块模板机制把“编辑器初始状态”变成了声明式配置PHP 侧通过文章类型对象的template/template_lock或 CPT 注册参数template声明JS 侧通过registerBlockType配合InnerBlocks的template/templateLock属性声明嵌套模板用三元组数组递归表达块树锁定分两级template_lockcontentOnly/all/insert控制区域行为并沿 InnerBlocks 继承块级lockremove/move优先级更高二者组合可实现精细的编辑自由度控制。进一步可阅读仓库中的参考资料块 API 参考目录、Meta Box 教程模板的完整实战示例、block-library 标题块 block.json模板属性的权威来源以及 InnerBlocks 组件文档。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考