跳转到正文

存储

默认情况下,所有字段值都会作为区块属性存储在文章内容的区块注释中。存储功能还允许将值存储在文章元数据(wp_postmeta)或选项(wp_options)中,以便在区块上下文之外访问这些值。

为什么使用存储?

区块属性存储在文章内容的 HTML 注释中,因此只有解析区块内容时才能访问。使用其他存储位置后,你可以:

  • 使用 meta_query 按字段值查询文章
  • 在无头架构中通过 REST API 访问值
  • 与其他插件(例如 SEO)或缓存插件共享数据
  • 创建可跨文章保留的全局设置

存储类型

类型 位置 范围 适用场景
postMeta wp_postmeta 表 每篇文章 可查询的文章专属数据
option wp_options 表 全局(整个站点) 站点设置、共享值

注意

区块属性始终会自动存储(位于文章内容的 HTML 注释中)。storage 属性会添加额外的存储位置,不会取代区块存储。

配置

在任意字段定义中添加 storage 属性:

JSON
{
  "name": "blockstudio/example",
  "title": "Example Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "subtitle",
        "type": "text",
        "label": "Subtitle",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "my_subtitle"
        }
      }
    ]
  }
}

存储属性

属性 类型 说明
type string | string[] 额外的存储location(s):"postMeta"、"option"
postMetaKey string 自定义元数据键(默认:{block_name}_{field_id})
optionKey string 自定义选项键(默认:{block_name}_{field_id})

单一存储与多重存储

JSON
// Add post meta storage
"storage": {
  "type": "postMeta"
}

// Add both post meta and option storage
"storage": {
  "type": ["postMeta", "option"]
}

工作原理

  1. 注册:WordPress 加载时,Blockstudio 会根据字段配置注册元数据键和设置
  2. 编辑:值在编辑器中作为区块属性管理(始终存储在区块中)
  3. 保存:保存文章时同步文章元数据。发布文章或已发布文章的字段值发生变化时,同步站点选项。

自动保存和修订版本不会同步这两种存储位置。草稿、待审核、私密和定时发布的文章可以更新各自的文章元数据,但不会更改站点当前的选项。定时发布的文章会在 WordPress 发布时同步选项。

值会按原样复制,包括反斜杠、引号和嵌套的重复器值。不要为了弥补 WordPress 元数据存储而对字段值添加转义;Blockstudio 会处理这道边界。站点选项保留相同的字面值,不会额外添加斜杠。

如果早期版本从文章的元数据副本中删除了反斜杠,请在升级后再次保存文章。系统会使用区块属性中的原始字段值来刷新元数据副本。

保存站点选项

选项会在整个站点范围内共享。发布新的区块时,会写入其已保存属性中提供的选项字段。之后保存时,系统会将每个字段与该区块先前保存的版本进行比较,并且只写入发生变化的值。保存文章标题,或保存另一篇文章上未更改的旧区块副本,都不会覆盖较新的选项值。

未包含在已保存属性中的字段会使其选项保持不变。这样也能在添加新字段到 block.json 时保护现有选项。显式的 null 会删除选项;空字符串、false、0 和空数组都会作为值保存。移除区块不会删除其选项。

使用一个指定的已发布区块来管理每个共享选项。如果多个区块有意修改同一选项,则最后保存的更改值生效。存储不会将当前选项加载到每个区块中:每个区块都会在文章内容中保留自己的字段值。

对于基于文件的页面,持久区块 key 可让 Blockstudio 在区块于文档中移动后仍能识别同一个区块。没有键的区块会根据区块名称和位置进行匹配。

访问已存储的值

在区块模板中

在区块模板中,可随时通过 $attributes 获取字段值:

PHP

PHP
<div>
  <h1><?php echo $a['subtitle']; ?></h1>
</div>

Twig

Twig
<div>
  <h1>{{ a.subtitle }}</h1>
</div>

文章元数据(区块上下文之外)

存储在 postMeta 中的值可在 WordPress 的任何位置访问:

PHP

PHP
// Get meta value
$subtitle = get_post_meta( $post_id, 'my_subtitle', true );

// Query posts by meta value
$posts = get_posts([
  'meta_key'   => 'my_subtitle',
  'meta_value' => 'Hello World',
]);

Twig

Twig
{# Using Timber #}
{{ post.meta('my_subtitle') }}

{# Or via function #}
{{ function('get_post_meta', post.id, 'my_subtitle', true) }}

也可以通过 REST API 访问文章元数据:

命令行
GET /wp-json/wp/v2/posts/123
# Response includes: { "meta": { "my_subtitle": "Hello World" } }

选项(全局值)

存储在 option 中的值可在整个站点范围内访问:

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

Twig
{{ function('get_option', 'site_company_name') }}

示例

SEO 元字段

将 SEO 数据存储在文章元数据中,以便与 SEO 插件兼容:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "seo_title",
        "type": "text",
        "label": "SEO Title",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_title"
        }
      },
      {
        "id": "seo_description",
        "type": "textarea",
        "label": "Meta Description",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_metadesc"
        }
      }
    ]
  }
}

添加文章元数据存储,以便按字段值查询文章:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "featured",
        "type": "toggle",
        "label": "Featured",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "is_featured"
        }
      }
    ]
  }
}

查询精选文章:

PHP
$featured_posts = get_posts([
  'meta_key'   => 'is_featured',
  'meta_value' => '1',
]);

全局站点设置

将站点范围内的配置存储在选项中:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "company_name",
        "type": "text",
        "label": "Company Name",
        "storage": {
          "type": "option",
          "optionKey": "site_company_name"
        }
      },
      {
        "id": "support_email",
        "type": "text",
        "label": "Support Email",
        "storage": {
          "type": "option",
          "optionKey": "site_support_email"
        }
      }
    ]
  }
}

在站点的任何位置访问:

PHP
<footer>
  <p>&copy; <?php echo get_option( 'site_company_name' ); ?></p>
  <p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>

文章元数据和选项

对于需要同时支持文章级和全局访问的数据:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "important_value",
        "type": "text",
        "label": "Important Value",
        "storage": {
          "type": ["postMeta", "option"],
          "postMetaKey": "important_meta",
          "optionKey": "important_option"
        }
      }
    ]
  }
}

默认键名

如果未指定自定义键,Blockstudio 会自动生成一个:

存储类型 默认键格式 示例
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

区块名称会经过清理(斜杠替换为下划线)。

警告

建议在生产环境中使用自定义键。重命名区块后,默认键可能会发生变化。