Dennis · 2026年7月23日
Blockstudio 7.5
Blockstudio 7.5 完善了 Blockstudio 的文件优先工作流:自定义字段类型、基于文件的 Site Editor 模板、区块孤岛、Storh 数据库存储、逻辑发现源、可组合的区块标签,以及更快的部署和运行时路径。
可复用的自定义字段已经支持项目定义一组现有字段,并通过 type: "custom/{name}" 重复使用。自定义字段类型解决的是另一个问题。它们让主题或插件可以注册新的命名空间字段类型,提供专属的编辑器控件,并将值作为普通的 Blockstudio 数据存储。
简而言之:
- 逻辑发现源:运行时可以提供组合后的逻辑主题清单,其中包含来源信息和缓存标识,而 Blockstudio 仍负责发现、同级文件解析、生成资产、Canvas 和 Tailwind 行为。
- PHP字段类型注册表:主题和插件可以注册带命名空间的字段类型,例如
acme/dimensions,并配合bs_register_field_type()或blockstudio/field_types过滤器使用。 - 编辑器控件注册表:自定义编辑器脚本可以调用
window.blockstudio.registerFieldType(),并在常规 Blockstudio 字段 UI 中呈现相应的 React 控件。 - 结构化值:自定义字段可以存储字符串、数字、布尔值、数组或对象,而无需通过选项字段规范化来强制转换对象值。
- 存储支持:文章元数据和基于选项的自定义字段可以声明其值类型和 REST 架构,包括对象和数组值。
- 原生集成:自定义字段类型可用于组、标签页、重复器、可复用自定义字段、模板和扩展模板路径中。
- 站点编辑器模板:主题可以从
template.json、part.json和 Blockstudio 模板文件定义wp_template和wp_template_part源。 - 区块岛:区块可以先呈现可安全缓存的外壳,然后在页面加载后填充内容,或批量获取与请求相关的片段。
- Storh数据库存储:
bs.db可以在 uploads 中使用按记录分文件的索引存储,保留公开整数 ID,并通过 WP-CLI 从 JSONC 迁移到 Storh。 - 解析器和 bsui 改进:映射富文本段落所需的自定义解析器连接代码更少;
InnerBlocks可以使用分词后的allowedBlocks;嵌套bs_render_block()输出在编辑器预览中与前端呈现一致;bsui/button增加了图标和更便捷的样式钩子。 - 可组合区块标签:前缀标签可以通过另一个前缀解析(
<theme-ui-input>到bsui/input),前缀和别名标签也会在区块模板输出中呈现,而不只是在页面内容中。 - 适用于各种主机的构建缓存:运行时和编辑器缓存现在默认存放在 uploads 之外,支持配置位置,并会清理过期条目,避免长期运行的项目累积缓存文件。
- 增量页面协调:部署工具可以协调完整的文件页面清单、跳过未更改的文章、准确报告更改内容,并在激活后保存经验证的源标识。
- 更快的热缓存呈现:有效的运行时缓存会在发现之前完成填充;并发冷请求只会发布一个原子结果;Tailwind 会维护适合整个站点规模的缓存,并复用编译器状态。
- 安全的批量呈现:导出器可以在文档之间重置请求范围内的呈现状态,而无需重建发现结果;区块呈现时也可以收集源依赖项。
新功能
7.5 在发现、模板和存储方面带来了一系列新功能。
逻辑发现源
Blockstudio 通常从物理主题目录中发现文件。7.5 增加了一个较底层的源 API,供运行时从覆盖层、预览、生成的文件、远程挂载或其他组合清单中组装主题时使用。
集成可以提供最终的逻辑文件树,同时 Blockstudio 仍负责区块、字段、页面、样板、站点编辑器、Canvas、资产和 Tailwind 行为:
use Blockstudio\Inventory_Discovery_Source;
add_filter(
'blockstudio/discovery/sources',
function (array $sources, string $context): array {
if ('blocks' !== $context) {
return $sources;
}
return [
new Inventory_Discovery_Source(
'preview:feature-card',
'/runtime-preview/feature-card/blockstudio',
[
'card/block.json' => [
'path' => '/theme/blockstudio/card/block.json',
'provenance' => ['layer' => 'parent'],
],
'card/index.php' => [
'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
'provenance' => ['layer' => 'preview'],
],
],
'preview-fingerprint'
),
];
},
10,
2
);
即使同级文件来自不同的物理根目录,逻辑路径也会保持稳定。源 ID 和指纹会构成运行时及 Tailwind 缓存标识;监视输入会使这些标识失效;来源信息则会控制生成文件的写入位置。普通主题的默认文件系统源保持不变。
基于文件的站点编辑器模板
页面和样板已经支持团队将内容结构保存在文件中。7.5 将这一模式扩展到了站点编辑器本身。
theme/
templates/
front-page/
template.json
index.php
parts/
header/
part.json
index.php
{
"slug": "front-page",
"title": "Front Page"
}
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<block name="core/post-content" />
</main>
</div>
Blockstudio 使用与页面和样板相同的解析器编译源,然后将结果作为普通站点编辑器模板或模板部件提供给 WordPress。站点编辑器可以看到该模板,前端可以呈现它,而 WordPress 仍负责管理自定义项。
最后这一点很重要。基于文件的模板是源回退方案。如果用户在站点编辑器中保存模板,WordPress 会创建常规的 wp_template 或 wp_template_part 数据库自定义项,并以该版本为准。重置自定义项后,就会再次显示最新的文件源。
增量页面部署
基于文件的页面在 7.5 中新增了部署协调 API。自 7.6.2 起,只有明确的 API 和 wp bs pages sync 是同步入口;常规请求不会应用源更改:
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
该流程会发现完整的目标页面清单、比较内容和同步引擎指纹,并报告已创建、已更新、未更改、已移除和失败的页面。指纹相同的页面不会执行文章或文章元数据写入。只有在发现过程无错误完成后,才会清理缺失的受管理页面。
协调操作会返回确定性的源标识,但不会将部署标记为成功。部署工具只会在匹配的文件和路由已激活并通过验证后保存该标识。常规的 WP-CLI 引导流程会注册缓存的集合文章类型和重写规则,不会发现并同步每个页面。
区块岛
大多数 Blockstudio 区块都由服务器呈现。这很适合 WordPress,但会带来一个常见的缓存问题:一个个性化区块就可能让整个页面难以缓存。
区块岛在区块层级划分了这个边界。
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
动态岛在首次响应中只呈现可安全缓存的占位内容。随后,浏览器会为页面上所有已就绪的动态岛发送一次批量请求,而 Blockstudio 会在访客的真实请求上下文中呈现这些片段。
这意味着完整页面缓存可以存储页面外壳,同时购物车数量、账户控件、权限限制的 UI 或其他针对用户的内容仍能保持最新。
<div class="cart-count-placeholder">Loading cart...</div>
<div class="cart-count">
<?php echo esc_html(acme_cart_count()); ?>
</div>
对于已经呈现可安全缓存的 HTML、只需要前端挂载信号的区块,请使用已水合的岛:
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
已水合的岛不会发起 REST 请求。它们会照常呈现,并在前端接收 blockstudio:island:hydrate 事件。
动态岛也适用于程序化呈现路径:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
也适用于区块标签:
<bs:acme-cart-count product-id="42" />
该端点的功能范围经过有意限制。它只会呈现已注册的 Blockstudio 动态区块,且这些区块必须明确标记为动态岛。属性会根据区块架构和岛的允许列表进行筛选,每个标记都带有由提供服务的 WordPress 站点生成的签名。
Storh 数据库存储
Blockstudio 的数据库层已经支持表、SQLite、JSONC、文章元数据和自定义文章类型。7.5 增加了 storage: "storh",供需要基于文件的存储、以获得更安全的并发写入和从架构派生索引的项目使用;这些项目不希望实时记录与区块源文件一同提交。
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Storh 记录存放在 uploads 中:
wp-content/uploads/blockstudio/db/my-theme-my-block/default/
公开的 API 保持不变。bs.db()、REST 和 Db::get() 仍会返回整数 id 值。在内部,Blockstudio 会将这些 ID 映射到 Storh 的 UUIDv7 文档 ID,因此现有客户端代码无需更改。
每个已声明的架构字段都会建立索引,以支持相等筛选;数值和类日期字段会建立范围索引;明确的唯一性提示也会向下传递。对于从 JSONC 种子文件起步的项目,新的 CLI 迁移会保留源文件,并写入等效的 Storh 存储:
wp bs db migrate my-theme/app subscribers --to=storh
这样一来,JSONC 更适合作为简单、可提交的种子/配置格式,而 Storh 则成为可写生产数据更理想的默认文件后端。
解析器和 bsui 改进
对于更多依赖基于文件的模板和打包 UI 的项目,7.5 也完善了一些经常会用到的小功能。
元素映射现在无需自定义构建器,就能处理常见的富文本段落情况。如果 <p> 映射到带有 content 富文本属性的已注册非核心 Blockstudio 区块,简单的内部文本就会复制到该属性中。嵌套标签和映射的子元素仍会解析为内部区块。
InnerBlocks 支持在模板中使用分词后的 allowedBlocks:
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
'core/paragraph',
'category:content',
'bsui/field',
])); ?>" />
支持的令牌包括 namespace/*、category:<slug> 和 @theme。这些令牌会在编辑器接收模板前由服务器展开,因此前端呈现路径保持不变。
程序化嵌入也更可预测。现在,即使在另一个区块的编辑器预览中调用,bs_render_block() 和 bs_block() 也会将嵌入的区块呈现为由前端解析的 HTML。因此,嵌套区块不会将原始 <RichText /> 或 <InnerBlocks /> 伪组件泄漏到预览标记中。
对于打包的 UI,bsui/button 现在支持 icon 属性和 iconPosition。打包的 bsui/* 内联样式会输出到 @layer bsui 级联层中,并且可以通过 blockstudio/ui/button/variants-style 以及现有的 blockstudio/blocks/attributes 过滤器扩展按钮变体。
区块标签的组合能力也进一步增强。前缀可以通过另一个前缀解析,因此在 ui 命名空间前缀上使用 theme 项目前缀的 <theme-ui-input /> 会解析为 bsui/input。已注册的前缀和别名标签现在也会在区块模板输出中呈现,而不仅限于页面内容,因此模板可以直接输出它们,而无需调用 bs_render_block()。
通过 blockstudio/block_tags/builders 注册的自定义区块构建器也会一致地参与标签和映射元素的解析。显式渲染器过滤器仍会在之后运行,并可以覆盖构建器。
更快的热缓存请求和导出
运行时和编辑器缓存现在默认存放在 wp-content/blockstudio/cache,而不是 uploads。可以通过 cache.path 或 blockstudio/cache/dir 更改位置,这样即使主机禁止在 uploads 中存放 PHP 负载,也能使用持久缓存。运行时、编辑器资产和 Tailwind 缓存也会自动清理过期条目,因此长期运行的项目不再会让缓存文件在磁盘上无限累积。
热缓存前端请求现在会先填充有效的运行时注册表,再构建发现源。这样就能跳过递归源发现、区块构建、字段解析和重复的缓存键树遍历。生产和预发布环境中的请求默认会在 20 秒内信任经过验证的监视快照;本地和开发环境仍会在每次请求时进行检查。
冷缓存的创建采用单航班机制。一个请求负责构建并原子化地发布负载,同时其他并发请求会等待结果完成。Tailwind 现在默认会将多达 1,000 个已编译条目保留 30 天,并复用热缓存中的编译器构建状态,因此适合整个站点规模的路由集合不再会频繁淘汰小型缓存中的条目。
长时间运行的导出器可以在文档之间调用 Blockstudio\Batch_Render::reset()。这会清除请求范围内的计数器、资产、岛、布局和 Tailwind 生成状态,而无需重建发现结果。blockstudio/render/dependencies 过滤器会公开每个已呈现区块使用的模板和资产路径,供依赖关系图使用。
可靠性与兼容性
以下几项修复完善了此版本:
- 现在,通过
blockstudio/blocks/attributes更改的字段定义会同时影响呈现时的选项验证和编辑器架构。带类型的数值和布尔选项值也能保持一致解析。 - 编辑器区块包装器会使用与前端呈现相同的生成类;Canvas 也可以通过新的
blockstudio/editor/canvas/body_class过滤器复制已配置的前端 body 类。 - 内容同步会在执行破坏性写入前验证完整的源计划,将清理操作限制在已配置的内容集合内,并报告文件写入失败,而不会推进相应实体的同步状态。
- 在符号链接活动主题或父主题中打包的 Composer 会从公开主题 URL 解析编辑器资产。
- 带键的文件页面会保留由编辑器管理的 Blockstudio 字段值,在同步时迁移旧的嵌套键结构,并接受数值零作为有效键。
- 动态岛会在请求属性过滤器运行前验证签名,忽略未签名的请求上下文,恢复同源登录访客状态,并避免匿名用户之间的个性化缓存冲突。
- 原始 Markdown 页面端点现在会遵守文章可见性和密码保护设置。
- 编辑器控件对空条件、复选框全选切换值、异步选项刷新、动态呈现顺序,以及重复器中的 RichText 或 WYSIWYG 状态处理得更加可靠。
自定义字段类型
更多关于上文所介绍自定义字段类型的信息。
为什么需要自定义字段类型?
Blockstudio 开箱即用时应当实用,但实际项目往往需要特定领域的控件:间距令牌选择器、设计系统颜色角色、响应式尺寸、图标来源、产品选择器,或映射到结构化值的编辑控件。
在 7.5 之前,这些项目只能组合多个内置字段,或自行分叉编辑器。7.5 提供了一个受支持的折中方案:Blockstudio 负责字段生命周期,项目负责控件。
add_action('init', function () {
wp_register_script(
'acme-field-dimensions',
get_stylesheet_directory_uri() . '/fields/dimensions.js',
['blockstudio-blocks', 'wp-components', 'wp-element'],
'1.0.0',
true
);
bs_register_field_type('acme/dimensions', [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
'storage' => [
'type' => 'object',
'rest_schema' => [
'type' => 'object',
'additionalProperties' => ['type' => 'string'],
],
],
]);
});
const { createElement: el } = wp.element;
const { TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/dimensions', {
component(props) {
const value =
props.value &&
typeof props.value === 'object' &&
!Array.isArray(props.value)
? props.value
: {};
const sides = props.sides || ['top', 'right', 'bottom', 'left'];
return el(
'div',
{},
sides.map((side) =>
el(TextControl, {
key: side,
label: side,
value: value[side] || '',
onChange(nextValue) {
props.onChange({
...value,
[side]: nextValue,
});
},
}),
),
);
},
});
然后,这个字段就能像原生字段一样用于 block.json:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "bottom"],
"default": {
"top": "md",
"bottom": "md"
}
}
]
}
}
常规模板值
保存的值可以像其他 Blockstudio 属性一样,在 PHP、Twig 和 Blade 中使用。
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
相同的对象路径也适用于扩展模板:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
兼容性说明
现有内置字段类型保持不变。现有的 custom/{name} 可复用字段组也保持不变。自定义字段类型名称必须使用小写并带命名空间,例如 acme/dimensions;custom/ 和 blockstudio/ 命名空间仍为保留名称。
如果 PHP 注册了字段类型,但其编辑器脚本没有注册相应控件,Blockstudio 会保留已保存的值,并在编辑器中显示不可编辑的提示。如果字段类型未在 PHP 中注册,Blockstudio 就不会将其包含在生成的 WordPress 属性中。
7.5.1 维护更新
7.5.1 修复了在准备多个选择值以供呈现时发出的数组转字符串转换警告。保存和呈现的值原本就是正确的,但调试日志中每次呈现字段时都可能出现一条警告。
随附的 blockstudio/phpstan v0.1.7 更新还支持识别在 PHP、Twig、Blade 中嵌套于匿名组内的字段,以及推断出的模板属性结构。现有项目可以通过 composer update blockstudio/phpstan 获取此软件包修复。