Dennis · 2026年4月10日
Blockstudio 7.2
Blockstudio 7.2 沿着两个方向同时扩展了框架。
第一个方向是单个项目中的可见性和工作流:新增管理员概览、数据库浏览器、管理员注册表浏览器,以及用于共享 Sass 配置的 SCSS 前置代码。
第二个方向是围绕 Blockstudio 的生态系统:提供用于分发区块的注册表 CLI(类似于为 WordPress 打造的 shadcn),以及 PHPStan 扩展,为模板、区块标签、db.php、rpc.php、cron.php 和相关架构文件带来 TypeScript 风格的类型安全。
这两个方向都旨在解决同一件事:让大型 Blockstudio 项目更易于理解、扩展和共享。
管理体验
两项新增功能让你更容易在 wp-admin 中浏览大型项目。
管理员概览
Blockstudio 现在在 工具 > Blockstudio 下新增了一个管理页面。你可以在此统一查看系统从文件系统中注册的内容。
概览包含以下专用标签页:
- 区块
- 扩展
- 字段
- 页面
- 架构
除了概览之外,管理区域现在还设有专门的数据库板块。它会列出所有已注册的 Blockstudio\Db 架构,并允许你直接在 wp-admin 中查看实际记录。
该页面使用原生 WordPress DataViews 表格,而不是自定义面板网格。这样可以使 UI 与 wp-admin 保持一致,并在项目中有几十或上百个注册项时依然实用。
在小型安装中,你可以把运行时状态记在脑中。但在较大的代码库中,这就行不通了。你会开始提出这样的问题:
- 当前实际注册了哪些区块?
- 哪些扩展针对
core/*,哪些针对单独的区块? - 哪些页面已同步?它们属于哪些文章类型?
- 项目中有哪些可复用字段?
- 注册了哪些架构?它们使用什么存储后端?
此前,你只能通过查看目录、打开 JSON 文件和逐步检查 PHP 来综合寻找答案。现在,概览将这些信息集中呈现在管理界面中。
每个标签页都旨在解答不同的问题:
- 区块显示已注册的区块类型、渲染模式、API 版本和属性数量
- 扩展显示其目标区块,以及优先级和渲染详情
- 字段快速列出可复用的自定义字段定义
- 页面显示基于文件且已同步的页面,包括文章类型、状态、模板引擎和同步状态
- 架构显示已注册的存储架构,包括后端、字段数量和权限范围
数据库浏览器特意与初始概览负载分开。页面加载时不会序列化每一行数据,而是只预先本地化可用的架构,并在你打开数据库标签页时按需获取记录。这样,即使项目的数据集较大,管理界面也依然实用,数据集位于 db.php 后面。
此首个版本特意聚焦于由架构支持的注册项。它不是设置页面,而是检查页面。
如果你完全不需要它,可以彻底禁用:
add_filter('blockstudio/admin/enabled', '__return_false');
管理后台注册表浏览器
概览旁边还有第二个标签页:注册表。它可以浏览主题的 blocks.json 中配置的远程区块注册表,并让你直接从 WordPress 管理后台导入区块,无需接触 CLI。
{
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.example.com/registry.json",
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
浏览器会获取每个已配置的注册表,列出所有可用区块,并显示这些区块是否已在本地安装或可供导入。每一行都有一个“导入”按钮,可将区块文件下载到主题中配置的目录。已安装的区块则会显示“重新导入”按钮。
支持经过身份验证的注册表,使用包含 headers 的对象格式,其中还支持 ${ENV_VAR} 插值,因此令牌不会进入版本控制。
这样一来,浏览和使用注册表就成为管理后台的一等体验,而不只是 CLI 工作流。
注册表 CLI
注册表功能的另一部分是一个独立的 CLI:blockstudio/registry。
这是一个面向 WordPress 区块的 shadcn 风格工具。不需要 npm 包,也不需要构建步骤。运行命令后,区块源代码会复制到你的项目中,完全由你掌控。
npx blockstudio init
npx blockstudio add ui/tabs
CLI 适用于任何区块类型:Blockstudio 区块、@wordpress/create-block 输出、普通 PHP 区块。注册表不关心文件夹里有什么,只会读取 registry.json 中的文件清单,并准确复制其中列出的文件。
区块作者可以在任意 URL 发布一个 registry.json(GitHub 原始内容、S3 或自定义服务器),列出可用区块及其元数据、依赖项和文件清单。用户将 URL 添加到自己的 blocks.json,即可按名称拉取区块。
CLI 支持:
- 依赖解析:区块可以声明对其他区块的依赖,系统会自动解析并检测循环依赖
- 多注册表冲突处理:如果多个注册表中存在同名区块,CLI 会提示你选择其中一个
- 经过身份验证的注册表:支持 bearer 令牌、基本身份验证和自定义标头,并支持环境变量插值
- 交互式 TUI:使用 Ink 构建,包含旋转指示器、选择提示和进度指示器
- 非交互模式:
--yes标志,以及 CI 和管道输入时的自动回退 - 搜索与列表:从命令行浏览注册表
该包附带 130 个测试,涵盖架构、依赖解析、HTTP 获取、文件写入、所有命令流程以及交互式 Ink UI。
完整文档请参阅 注册表blockstudio.dev/registry。
PHPStan 扩展
另一项重要新增内容是 blockstudio/phpstan:一个 PHPStan 扩展,为 Blockstudio 用户带来开发者所期待的类型安全 TypeScript。
composer require --dev blockstudio/phpstan
该扩展会在分析时读取项目的实际架构,并将生成的类型反馈给 PHPStan。现在涵盖 PHP 模板、Twig、Blade、区块标签、类型化数据库记录、设置路径、钩子名称,以及跨 block.json、field.json、扩展 JSON、page.json、db.php、rpc.php、cron.php 和 blockstudio.json 的架构验证。
类型安全的区块模板
对 $a 的字段访问会根据同级的 block.json 进行验证:
<?php
/** @var array<string, mixed> $a */
echo $a['title']; // OK
echo $a['cta']['href']; // OK
echo $a['typo']; // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?
类型安全的数据库记录
Db::get() 会根据你的 db.php 架构返回类型化实例。记录结构根据实际字段构建:
return [
'storage' => 'table',
'fields' => [
'email' => ['type' => 'string', 'required' => true],
'name' => ['type' => 'string'],
],
];
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);
echo $record['email']; // PHPStan: string
echo $record['name']; // PHPStan: string|null
echo $record['typo']; // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}
架构验证
无效的架构文件会在分析时被捕获:block.json、field.json、扩展 JSON、page.json、db.php、rpc.php、cron.php 和 blockstudio.json。缺少名称、字段类型错误、定义格式错误、已弃用的简写布尔值("tailwind": true,而不是嵌套对象)都会报告源文件中的准确行号。
设置路径验证
Settings::get() 调用会根据已知的设置架构进行验证:
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?
钩子名称验证
过滤器和操作钩子的名称也会进行同样的验证:
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?
该扩展还为整个 Blockstudio 公共 API 提供存根:Db、Settings、Field_Registry、Build 以及全局辅助函数。无需在开发机器上安装插件源代码,即可获得所有 Blockstudio API 的自动补全和类型检查。
编写便利功能
另外还有两项较小的编写便利功能,为本次发布画上句号。
全局 SCSS 前置代码
Blockstudio 已支持 SCSS 编译,但有一个令人头疼的摩擦点:共享 Sass 设置。
如果你想使用一组通用变量、函数或混入,就必须在每个 SCSS 文件中导入它们。很快就会变得重复繁琐,尤其是在大型设计系统或像 Bootstrap 这样的 Sass 工具包中。
7.2 正好为此新增了一个前置代码钩子:
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
return '@import "functions";' . "\n"
. '@import "variables";' . "\n"
. '@import "mixins";';
}, 10, 3);
结合现有的 blockstudio/assets/process/scss/import_paths 过滤器,只需定义一次共享的 Sass 表面,就能让每个编译文件都使用它。
区块样式表可以专注于所需的实际样式:
.hero {
@include media-breakpoint-up(lg) {
padding: 4rem;
}
}
无需在每个区块资源中重复导入。这不是一种特殊的“Bootstrap 支持”模式,而是一个通用钩子,可在整个项目中共享 Sass,无论它来自 Bootstrap 还是你自己的内部工具包。
PHP 原生区块 API 定义
7.2 还为全栈区块 API 新增了可选的 PHP 原生语法。数组仍是默认格式,并且完全受支持,没有任何内容被替换。不过,如果你更喜欢命名参数、枚举和属性,而不是嵌套配置数组,现在可以选择这种写法。
对于 rpc.php,返回一个包含带属性方法的对象:
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;
return new class {
#[Rpc(access: Access::Session)]
public function subscribe(array $params): array {
return ['success' => true];
}
#[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
public function getStatus(array $params): array {
return ['status' => 'ok'];
}
};
对于 cron.php,同样的思路也适用于 #[Cron]:
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;
return new class {
#[Cron(schedule: Schedule::Hourly)]
public function heartbeat(): void {
}
};
对于 db.php,现在还有一层简易构建器:
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;
return Schema::make(
storage: Storage::Table,
fields: [
'email' => Field::string(required: true, format: 'email'),
'active' => Field::boolean(default: false),
],
);
这为较大的代码库带来了更好的平衡。你可以按需保留数组格式的简洁性;当区块的字段或端点超过几个时,也可以切换到更易于发现的 PHP 表面。
为何将这些内容一起发布
管理后台概览、注册表浏览器、注册表 CLI 和 PHPStan 扩展都在回答同一个问题:Blockstudio 项目不断扩展时,如何让它始终易于理解?
管理工具从项目层面回答这个问题:了解已注册的内容、从注册表引入区块,减少猜测。
CLI 从生态系统层面回答这个问题:让项目和团队能够共享区块,而不必将它们打包进 npm 包,也不必与构建系统周旋。
PHPStan 扩展从代码层面回答这个问题:在错误的字段访问、架构拼写错误和损坏的钩子回调进入运行时之前将其捕获。
这总体上就是 7.2 的方向:减少猜测和重复,提升可见性,并带来真正的类型安全。
错误修复
- 类字段:用户输入的自定义类名在失去焦点时会被静默丢弃,因为验证器只接受预定义的 Tailwind/设置列表中的类名。现在任何非空字符串都可以通过。
- 属性字段:移除一组属性后,保存的数据中仍残留
null条目。已从 lodashunset()(会将数组元素置空)改为splice()(会移除这些元素)。 - CSS 压缩器:TailwindPHP 压缩器会移除
+周围的空白字符,涉及calc()和clamp(),导致生成无效的 CSS,例如calc(1rem+0.5vw)。已在上游 TailwindPHP v1.3.1 中修复:通过考虑嵌套深度的字符遍历,仅移除括号深度为 0 时选择器组合符周围的空白字符。 - 区块插入器预览:在区块插入器预览中,
$isPreview始终为false,因为渲染缓存的哈希键中未包含渲染模式。现在编辑器渲染和预览渲染会生成独立的缓存条目。 - InnerBlocks 嵌套模板:
<InnerBlocks template="..."/>组件会从类似['core/group', {}, [['core/paragraph']]]的模板元组中丢弃第三个元素(子项),导致容器区块为空。现在会保留嵌套子项。