区块编辑器中的每个区块都包含在一个 HTML 包装器内，该包装器必须具备特定的属性才能在编辑器和前端正确运行。作为开发者，我们可以直接操作这些标记，WordPress 还提供了诸如 useBlockProps() 之类的工具来修改添加到区块包装器的属性。

在使用自定义样式或诸如 区块支持 等功能时，确保为区块包装器添加适当的属性尤为重要。

WordPress 中的区块可以通过三种不同的标记类型来定义，每种类型都发挥着独特的作用：

  • 编辑器标记 (Editor Markup)：这是区块在区块编辑器内的视觉表示。当通过 registerBlockType 在客户端注册区块时，它使用 Edit React 组件来定义。
  • 保存标记 (Save Markup)：当保存区块内容时，此标记会被保存到数据库中。它通过一个 save 函数指定，该函数也是在区块注册期间提供给 registerBlockType 的。如果区块不使用动态渲染，那么此保存标记将显示在前端。
  • 动态渲染标记 (Dynamic Render Markup)：当需要动态生成区块内容时，此标记就会发挥作用。它是在服务器端定义的，可以通过 register_block_type 中的 render_callback 函数或 block.json 中指定的 render.php 文件来定义。如果存在，此标记将覆盖任何保存的标记，并用于区块的前端显示。

对于 Edit 组件和 save 函数，重要的是使用标准 DOM 元素（如 <div>）作为包装器元素，或者使用将所有额外属性传递给原生 DOM 元素的 React 组件。使用 React 片段 (<Fragment>) 或 <ServerSideRender> 组件不适用于这些包装器。

编辑器标记

useBlockProps() 钩子由 @wordpress/block-editor 包提供，用于在 Edit 组件中定义区块的外部标记。

此钩子简化了几项任务，包括：

  • 为区块的 HTML 结构分配唯一的 id。
  • 添加各种可访问性和 data- 属性以增强功能和信息。
  • 纳入反映区块自定义设置的类和内联样式。默认情况下，这包括：
    • 用于通用区块样式的 wp-block 类。
    • 一个结合区块命名空间和名称的特定于区块的类，确保唯一且针对特定的样式能力。

在以下示例中，区块的编辑器标记使用 useBlockProps() 钩子在 Edit 组件中定义。

const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;

registerBlockType( ..., {
    edit: Edit
} );

参见 完整区块示例 中的 上述代码。

区块编辑器中的标记可能如下所示，其中类和属性会自动应用：

<p
    tabindex="0"
    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe"
    role="document"
    aria-label="Block: Minimal Gutenberg Block ca6eda"
    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe"
    data-type="block-development-examples/minimal-block-ca6eda"
    data-title="Minimal Gutenberg Block ca6eda"
    class="
        block-editor-block-list__block
        wp-block
        is-selected
        wp-block-block-development-examples-minimal-block-ca6eda
    "
>Hello World - Block Editor</p>

在区块的 Edit 组件中，使用 useBlockProps() 钩子并通过将其作为参数传递来包含额外的类和属性。（参见 示例）

当您使用 supports 属性启用功能时，任何相应的类或属性都会自动包含在 useBlockProps 返回的对象中。

保存标记

当将标记保存到数据库时，重要的是将 useBlockProps.save() 返回的属性添加到区块的包装器元素。 useBlockProps.save() 确保除了由区块支持 API 注入的任何 HTML 属性外，区块类名也能正确渲染。

考虑以下在客户端注册区块的代码。注意它是如何定义编辑区块时应使用的标记以及将区块保存到数据库时的标记的。

const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;
const save = () => <p { ...useBlockProps.save() }>Hello World - Frontend</p>;

registerBlockType( ..., {
    edit: Edit,
    save,
} );

参见 完整区块示例 中的 上述代码。

前端上的区块标记可能如下所示，其中类会自动应用：

<p class="wp-block-block-development-examples-minimal-block-ca6eda">Hello World – Frontend</p>

如果您想为区块的 save 函数添加任何额外的类或属性，它们应作为 useBlockProps.save() 的参数传递。（参见 示例）

当您为任何功能添加 supports 时，适当的类会添加到 useBlockProps.save() 钩子返回的对象中。在下例中的段落区块已添加了文本和背景颜色类。

<p class="
    wp-block-block-development-examples-block-supports-6aa4dd
    has-accent-4-color
    has-contrast-background-color
    has-text-color
    has-background
">Hello World</p>

生成此 HTML 的 示例区块 可在 区块开发示例 存储库中找到。

动态渲染标记

在动态区块中，前端标记是在服务器端渲染的，您可以利用 get_block_wrapper_attributes() 函数来输出必要的类和属性，就像您在 save 函数中使用 useBlockProps.save() 一样。（参见 示例）

<p <?php echo get_block_wrapper_attributes(); ?>>
    <?php esc_html_e( 'Block with Dynamic Rendering – hello!!!', 'block-development-examples' ); ?>
</p>