WordPress Gutenberg 嵌套块开发完全指南

WordPress Gutenberg 嵌套块开发完全指南

gutenberg The Block Editor project for WordPress and beyond. Plugin is available from the official repository. 项目地址: https://gitcode.com/gh_mirrors/gu/gutenberg

什么是嵌套块

在 WordPress Gutenberg 编辑器中，嵌套块是指一个块可以包含其他块的机制。这种设计模式让开发者能够创建更复杂的结构化内容，比如列布局、选项卡组、手风琴等组件。

核心组件：InnerBlocks

实现嵌套块功能的核心是 InnerBlocks 组件，它提供了以下关键能力：

1. 作为容器承载其他块
2. 控制允许插入的块类型
3. 设置默认块模板
4. 管理块的父子关系

基础用法示例

import { registerBlockType } from '@wordpress/blocks';
import { InnerBlocks, useBlockProps } from '@wordpress/block-editor';

registerBlockType('my-plugin/container-block', {
  edit: () => {
    const blockProps = useBlockProps();
    return (
      <div {...blockProps}>
        <InnerBlocks />
      </div>
    );
  },
  save: () => {
    const blockProps = useBlockProps.save();
    return (
      <div {...blockProps}>
        <InnerBlocks.Content />
      </div>
    );
  }
});

高级控制功能

1. 限制允许的块类型

通过 allowedBlocks 属性可以限制容器内允许插入的块类型：

const ALLOWED_BLOCKS = ['core/heading', 'core/paragraph'];
<InnerBlocks allowedBlocks={ALLOWED_BLOCKS} />

2. 设置默认块

当用户点击添加按钮时，可以指定默认插入的块类型及其属性：

<InnerBlocks
  defaultBlock={['core/paragraph', { placeholder: '输入内容...' }]}
  directInsert
/>

3. 预定义模板

使用 template 属性可以预设初始内容结构：

const TEMPLATE = [
  ['core/image', {}],
  ['core/heading', { level: 2, placeholder: '标题' }],
  ['core/paragraph', { placeholder: '内容描述...' }]
];

<InnerBlocks 
  template={TEMPLATE}
  templateLock="all"
/>

templateLock 有三个可选值：

• all：完全锁定，不能修改顺序或添加新块
• insert：允许重新排序，但不能添加新块
• false：完全开放（默认值）

块关系管理

Gutenberg 提供了两种块关系定义方式，用于控制嵌套块的可用性：

1. 父子关系 (Parent)

{
  title: '子块',
  parent: ['parent-block/name'],
  // 其他配置...
}

特点：

• 子块必须直接嵌套在父块中
• 不会出现在其他位置的块插入器中
• 示例：列(Column)必须直接位于列组(Columns)中

2. 祖先关系 (Ancestor)

{
  title: '后代块',
  ancestor: ['ancestor-block/name'],
  // 其他配置...
}

特点：

• 块可以嵌套在祖先块的任意层级中
• 提供了更灵活的嵌套结构
• 示例：评论作者名称可以出现在评论模板的任何位置

使用 React Hook 替代组件

Gutenberg 提供了 useInnerBlocksProps hook，它比 InnerBlocks 组件提供了更灵活的控制：

import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

function Edit() {
  const blockProps = useBlockProps();
  const innerBlocksProps = useInnerBlocksProps(blockProps);
  
  return <div {...innerBlocksProps} />;
}

优势：

1. 更简洁的标记结构
2. 可以解构出 children 进行更灵活的布局
3. 与 useBlockProps 更好地集成

实际开发建议

1. 明确块的关系：在设计嵌套块时，先规划好父子或祖先关系
2. 合理使用模板锁定：根据用户需求决定模板的灵活程度
3. 性能考虑：复杂的嵌套结构可能影响编辑体验，适度使用
4. 移动端适配：确保嵌套块在移动设备上有良好的操作体验

通过掌握这些嵌套块开发技术，你可以为 WordPress 创建出更加强大和灵活的内容结构组件。

gutenberg The Block Editor project for WordPress and beyond. Plugin is available from the official repository. 项目地址: https://gitcode.com/gh_mirrors/gu/gutenberg