云策 WordPress 开发者社区

块编辑器开发文档

区块的标记表示

查看官方原文 ↗
💡 云策文档标注

概述

本文档介绍了 WordPress 区块在数据库或 HTML 模板中的标记表示方式，基于 HTML 注释语法，用于区分区块边界并确保技术有效性。它涵盖了核心区块和自定义区块的命名规则、设置存储，以及静态与动态区块的标记差异。

关键要点

  • 区块使用 HTML 注释作为分隔符，以 wp: 前缀开头，核心区块省略命名空间（如 wp:image），自定义区块包含命名空间（如 wp:namespace/name）。
  • 区块设置和属性以 JSON 对象形式存储在注释中，支持单行、自闭合或包裹 HTML 内容。
  • 在 Block Editor 中，WordPress 解析标记以提取数据并呈现可编辑版本；在前端，再次解析以渲染最终 HTML 输出。
  • 静态区块通过 save 函数生成存储在数据库中的标记，并需通过验证确保一致性；动态区块通常设置 save 为 null，仅保存包含属性的占位注释，不存储 HTML 标记。
  • 标记差异可能触发验证错误，可通过区块弃用机制处理变更。

代码示例

<!-- wp:image {"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
    <img src="source.jpg" alt="" />
</figure>
<!-- /wp:image -->
<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->

注意事项

  • 动态区块的标记通常仅包含注释和属性，不存储 HTML，反映其服务器端生成的动态特性。
  • 开发者应参考 Data Flow 文章深入了解区块数据解析过程。
📄 原文内容

Blocks are stored in the database or within HTML templates using a unique HTML-based syntax, distinguished by HTML comments that serve as clear block delimiters. This ensures that block markup is technically valid HTML.

Here are a few guidelines for the markup that defines a block:

  • Core blocks begin with the wp: prefix, followed by the block name (e.g., wp:image). Notably, the core namespace is omitted.
  • Custom blocks begin with the wp: prefix, followed by the block namespace and name (e.g., wp:namespace/name).
  • The comment can be a single line, self-closing, or wrapper for HTML content.
  • Block settings and attributes are stored as a JSON object inside the block comment.

The following is the simplified markup representation of an Image block:

<!-- wp:image {"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
    <img src="source.jpg" alt="" />
</figure>
<!-- /wp:image -->

The markup for a block is crucial both in the Block Editor and for displaying the block on the front end:

  • WordPress analyzes the block’s markup within the Editor to extract its data and present the editable version to the user.
  • On the front end, WordPress again parses the markup to extract data and render the final HTML output.
Refer to the Data Flow article for a more in-depth look at how block data is parsed in WordPress.

When a block is saved, the save function—defined when the block is registered in the client—is executed to generate the markup stored in the database, wrapped in block delimiter comments. For dynamically rendered blocks, which typically set save to null, only a placeholder comment with block attributes is saved.

Here is the markup representation of a dynamically rendered block (save = null). Notice there is no HTML markup besides the comment.

<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->

When a block has a save function, the Block Editor checks that the markup created by the save function is identical to the block’s markup saved to the database:

  • Discrepancies will trigger a validation error, often due to changes in the save function’s output.
  • Developers can address potential validation issues by implementing block deprecations to account for changes.

As the example above shows, the stored markup is minimal for dynamically rendered blocks. Generally, this is just a delimiter comment containing block attributes, which is not subject to the Block Editor’s validation. This approach reflects the dynamic nature of these blocks, where the actual HTML is generated server-side and is not stored in the database.

Additional resources