跳转到正文

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 后面。

此首个版本特意聚焦于由架构支持的注册项。它不是设置页面,而是检查页面。

如果你完全不需要它,可以彻底禁用:

PHP
add_filter('blockstudio/admin/enabled', '__return_false');

管理后台注册表浏览器

概览旁边还有第二个标签页:注册表。它可以浏览主题的 blocks.json 中配置的远程区块注册表,并让你直接从 WordPress 管理后台导入区块,无需接触 CLI。

JSON
{
  "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
<?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 架构返回类型化实例。记录结构根据实际字段构建:

PHP
return [
  'storage' => 'table',
  'fields' => [
    'email' => ['type' => 'string', 'required' => true],
    'name'  => ['type' => 'string'],
  ],
];
PHP
$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() 调用会根据已知的设置架构进行验证:

PHP
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"?

钩子名称验证

过滤器和操作钩子的名称也会进行同样的验证:

PHP
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 正好为此新增了一个前置代码钩子:

PHP
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 表面,就能让每个编译文件都使用它。

区块样式表可以专注于所需的实际样式:

Scss
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}

无需在每个区块资源中重复导入。这不是一种特殊的“Bootstrap 支持”模式,而是一个通用钩子,可在整个项目中共享 Sass,无论它来自 Bootstrap 还是你自己的内部工具包。

PHP 原生区块 API 定义

7.2 还为全栈区块 API 新增了可选的 PHP 原生语法。数组仍是默认格式,并且完全受支持,没有任何内容被替换。不过,如果你更喜欢命名参数、枚举和属性,而不是嵌套配置数组,现在可以选择这种写法。

对于 rpc.php,返回一个包含带属性方法的对象:

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
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};

对于 db.php,现在还有一层简易构建器:

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 条目。已从 lodash unset()(会将数组元素置空)改为 splice()(会移除这些元素)。
  • CSS 压缩器:TailwindPHP 压缩器会移除 + 周围的空白字符,涉及 calc() 和 clamp(),导致生成无效的 CSS,例如 calc(1rem+0.5vw)。已在上游 TailwindPHP v1.3.1 中修复:通过考虑嵌套深度的字符遍历,仅移除括号深度为 0 时选择器组合符周围的空白字符。
  • 区块插入器预览:在区块插入器预览中,$isPreview 始终为 false,因为渲染缓存的哈希键中未包含渲染模式。现在编辑器渲染和预览渲染会生成独立的缓存条目。
  • InnerBlocks 嵌套模板:<InnerBlocks template="..."/> 组件会从类似 ['core/group', {}, [['core/paragraph']]] 的模板元组中丢弃第三个元素(子项),导致容器区块为空。现在会保留嵌套子项。