存储
默认情况下,所有字段值都会作为区块属性存储在文章内容的区块注释中。存储功能还允许将值存储在文章元数据(wp_postmeta)或选项(wp_options)中,以便在区块上下文之外访问这些值。
为什么使用存储?
区块属性存储在文章内容的 HTML 注释中,因此只有解析区块内容时才能访问。使用其他存储位置后,你可以:
- 使用
meta_query按字段值查询文章 - 在无头架构中通过 REST API 访问值
- 与其他插件(例如 SEO)或缓存插件共享数据
- 创建可跨文章保留的全局设置
存储类型
| 类型 | 位置 | 范围 | 适用场景 |
|---|---|---|---|
postMeta |
wp_postmeta 表 |
每篇文章 | 可查询的文章专属数据 |
option |
wp_options 表 |
全局(整个站点) | 站点设置、共享值 |
注意
区块属性始终会自动存储(位于文章内容的 HTML 注释中)。
storage属性会添加额外的存储位置,不会取代区块存储。
配置
在任意字段定义中添加 storage 属性:
{
"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}) |
单一存储与多重存储
// Add post meta storage
"storage": {
"type": "postMeta"
}
// Add both post meta and option storage
"storage": {
"type": ["postMeta", "option"]
}
工作原理
- 注册:WordPress 加载时,Blockstudio 会根据字段配置注册元数据键和设置
- 编辑:值在编辑器中作为区块属性管理(始终存储在区块中)
- 保存:保存文章时同步文章元数据。发布文章或已发布文章的字段值发生变化时,同步站点选项。
自动保存和修订版本不会同步这两种存储位置。草稿、待审核、私密和定时发布的文章可以更新各自的文章元数据,但不会更改站点当前的选项。定时发布的文章会在 WordPress 发布时同步选项。
值会按原样复制,包括反斜杠、引号和嵌套的重复器值。不要为了弥补 WordPress 元数据存储而对字段值添加转义;Blockstudio 会处理这道边界。站点选项保留相同的字面值,不会额外添加斜杠。
如果早期版本从文章的元数据副本中删除了反斜杠,请在升级后再次保存文章。系统会使用区块属性中的原始字段值来刷新元数据副本。
保存站点选项
选项会在整个站点范围内共享。发布新的区块时,会写入其已保存属性中提供的选项字段。之后保存时,系统会将每个字段与该区块先前保存的版本进行比较,并且只写入发生变化的值。保存文章标题,或保存另一篇文章上未更改的旧区块副本,都不会覆盖较新的选项值。
未包含在已保存属性中的字段会使其选项保持不变。这样也能在添加新字段到 block.json 时保护现有选项。显式的 null 会删除选项;空字符串、false、0 和空数组都会作为值保存。移除区块不会删除其选项。
使用一个指定的已发布区块来管理每个共享选项。如果多个区块有意修改同一选项,则最后保存的更改值生效。存储不会将当前选项加载到每个区块中:每个区块都会在文章内容中保留自己的字段值。
对于基于文件的页面,持久区块 key 可让 Blockstudio 在区块于文档中移动后仍能识别同一个区块。没有键的区块会根据区块名称和位置进行匹配。
访问已存储的值
在区块模板中
在区块模板中,可随时通过 $attributes 获取字段值:
PHP
<div>
<h1><?php echo $a['subtitle']; ?></h1>
</div>
Twig
<div>
<h1>{{ a.subtitle }}</h1>
</div>
文章元数据(区块上下文之外)
存储在 postMeta 中的值可在 WordPress 的任何位置访问:
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
{# 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
$company_name = get_option( 'site_company_name' );
Twig
{{ function('get_option', 'site_company_name') }}
示例
SEO 元字段
将 SEO 数据存储在文章元数据中,以便与 SEO 插件兼容:
{
"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"
}
}
]
}
}
可查询的精选内容
添加文章元数据存储,以便按字段值查询文章:
{
"blockstudio": {
"attributes": [
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
]
}
}
查询精选文章:
$featured_posts = get_posts([
'meta_key' => 'is_featured',
'meta_value' => '1',
]);
全局站点设置
将站点范围内的配置存储在选项中:
{
"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"
}
}
]
}
}
在站点的任何位置访问:
<footer>
<p>© <?php echo get_option( 'site_company_name' ); ?></p>
<p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>
文章元数据和选项
对于需要同时支持文章级和全局访问的数据:
{
"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 |
区块名称会经过清理(斜杠替换为下划线)。
警告
建议在生产环境中使用自定义键。重命名区块后,默认键可能会发生变化。