
Blockstudio 7.3 为框架新增了一层功能：可像其他区块一样渲染的可复用 UI 组件。

7.1 将区块变成了全栈应用，7.2 让大型项目更易于检查、验证和分发，而 7.3 则聚焦于构建和编辑这些应用的日常体验。

简而言之：

- **UI 组件**：由 WordPress Interactivity API 驱动的内置可选 `bsui/*` 组件库。
- **应用**：内置 `app/*` 示例，展示 UI 组件如何组合成更大的界面。
- **扩展编辑器**：提供更宽的抽屉，在侧边栏空间不足时编辑 Blockstudio 字段。
- **作用域资源选择器**：CSS 和 SCSS 资源可以使用 `%selector%` 直接定位区块包装器类。
- **插件依赖**：区块可以要求指定的 WordPress 插件处于启用状态，并可选用版本约束。
- **编辑器策略**：`blockstudio.json` 可使用由 WordPress 的 PHP 支持的编辑器钩子，配置全局区块、样板和媒体行为。
- **区块标签别名**：为区块标签编写提供自定义别名。
- **静态分析和文档**：增强对外部区块库的 PHPStan 覆盖，并为设置和钩子生成文档。
- **页面和编辑器修复**：提高基于文件的页面解析、Tailwind 候选项检测、重置模式、渲染缓存隔离和编辑器预加载的可靠性。

## UI 库

7.3 附带内置组件库，以及基于该库构建的示例应用。

### UI 组件

Blockstudio 7.3 附带内置的 UI 库，命名空间为 `bsui/*`。这些组件都是普通的 Blockstudio 区块，因此可以使用你已经熟悉的区块标签语法，在模板、基于文件的页面、样板和文章内容中渲染。

UI 组件库目前处于测试阶段，我们正在收集更多反馈。7.3 的目标是推出首批组件，从实际项目中汲取经验，并在将 API 表面称为稳定版之前，完善名称、行为和默认值。

该库为可选启用：

```json title="blockstudio.json"
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}
```

启用后，可以直接渲染简单组件：

```html
<block name="bsui/button" label="Save" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
  name="bsui/input"
  nameAlt="email"
  type="email"
  placeholder="Email"
></block>
```

较短的 `bs:` 语法也可使用：

```html
<bs:bsui-button label="Save" variant="default" />
```

目标不是把 Blockstudio 变成页面构建器 UI 工具包，而是将常见的界面基础组件作为区块提供，让使用 Blockstudio 构建的应用无需在每个项目中重新创建按钮、对话框、标签页、选择框、表单字段、菜单、工具栏和反馈组件。

首批组件包括布局、操作、输入、覆盖层、导航、反馈、表单和数据展示等基础组件：

- `bsui/button`, `bsui/button-group`, `bsui/toggle`, `bsui/toggle-group`,
  `bsui/toolbar`
- `bsui/input`, `bsui/textarea`, `bsui/select`, `bsui/checkbox`,
  `bsui/radio-group`, `bsui/slider`, `bsui/switch`, `bsui/number-field`,
  `bsui/password-input`, `bsui/phone-input`, `bsui/otp-input`,
  `bsui/date-input`, `bsui/time-picker`
- `bsui/dialog`, `bsui/drawer`, `bsui/popover`, `bsui/menu`,
  `bsui/context-menu`, `bsui/menubar`, `bsui/tooltip`, `bsui/alert-dialog`
- `bsui/tabs`, `bsui/accordion`, `bsui/breadcrumb`, `bsui/pagination`,
  `bsui/navigation-menu`
- `bsui/card`, `bsui/table`, `bsui/stack`, `bsui/separator`,
  `bsui/aspect-ratio`, `bsui/badge`, `bsui/avatar`, `bsui/progress`,
  `bsui/meter`, `bsui/skeleton`, `bsui/spinner`, `bsui/kbd`
- `bsui/form`, `bsui/field`, `bsui/field-group`, `bsui/file-upload`,
  `bsui/color-picker`, `bsui/rating`

其中许多是复合区块。`bsui/tabs` 区块负责交互状态，而 `bsui/tabs-list`、`bsui/tabs-trigger` 和 `bsui/tabs-panel` 等子区块则描述结构。

```html
<block name="bsui/tabs" defaultValue="features">
  <block name="bsui/tabs-list">
    <block name="bsui/tabs-trigger" value="features" title="Features"></block>
    <block name="bsui/tabs-trigger" value="pricing" title="Pricing"></block>
  </block>
  <block name="bsui/tabs-panel" value="features">
    <p>Features content.</p>
  </block>
  <block name="bsui/tabs-panel" value="pricing">
    <p>Pricing content.</p>
  </block>
</block>
```

这样既能保持标记清晰易读，也由 Interactivity API 处理状态和行为。

### 应用示例

`app/*` 命名空间包含使用相同 UI 组件构建的示例。

它们不是独立的框架，而是大型 Blockstudio 界面的参考实现：复合区块、嵌套的 UI、Interactivity API 状态，以及 UI 组件与 RPC 或数据库驱动功能交互的场景。

```html
<block name="app/kitchen-sink"></block>

<block name="app/chat">
  <block name="app/chat-sidebar"></block>
  <block name="app/chat-header"></block>
  <block name="app/chat-messages"></block>
  <block name="app/chat-input"></block>
</block>
```

UI 库还附带自己的文档和在线组件参考。组件行为不只是模板的集合，而是框架契约的一部分，随着库的扩展也始终保持一致。

## 编写与编辑

多项改进让区块更易于编写和编辑。

### 扩展编辑器

在检查器侧边栏中编辑复杂区块，很快就会感到空间不足。中继器、代码字段、富文本和嵌套组尤其如此。

Blockstudio 7.3 在区块检查器中新增了扩展编辑器操作。它会从编辑器右侧打开一个更宽的抽屉，并在其中显示相同的 Blockstudio 字段。

关键在于，这仍然是同一套字段系统。它不会重复渲染字段，也不会引入第二条持久化路径；在扩展编辑器中所做的更改，会像在普通侧边栏中所做的更改一样，更新选中的区块。

如果侧边栏适合浏览内容，但输入时空间太局促，就可以使用它。

### 作用域资源选择器

Blockstudio 原本已支持代码字段的 `%selector%`。在 7.3 中，区块 CSS 和 SCSS 资源也可以使用相同的编写方式。

在 CSS 文件中，`%selector%` 会展开为区块的作用域类：

```css title="style.scoped.css"
%selector% {
  --hero-gap: var(--wp--preset--spacing--space-10);
}

%selector%.hero {
  border-bottom: 1px solid currentColor;
}

.hero__title {
  color: red;
}
```

这样就可以为实际的包装器元素设置样式：

```php title="index.php"
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
  <h1 class="hero__title">Hero</h1>
</section>
```

`*.scoped.css` 中的常规选择器仍然会定位后代元素。`%selector%` 是专门用于区块根元素的钩子。

### 插件依赖

区块现在可以在 `block.json` 的 `blockstudio` 键中声明对 WordPress 插件的依赖。

简单形式会检查列出的每个插件标识是否已启用：

```json title="block.json"
{
  "blockstudio": {
    "pluginDependencies": ["woocommerce"]
  }
}
```

对象形式则可添加版本约束：

```json title="block.json"
{
  "blockstudio": {
    "pluginDependencies": {
      "woocommerce": {
        "version": ">6"
      }
    }
  }
}
```

这些标识是 WordPress 插件标识，与 WordPress 核心的插件依赖系统一致。Blockstudio 会将已启用的插件解析为这些标识；如果缺少所需插件、插件未启用或版本低于要求，则跳过注册。

版本约束使用与 PHP 的 `version_compare()` 相同的比较模型。像 `"6"` 这样的普通版本号会被视为 `>=6`。

对于只有在某个插件可用时才有意义的区块，这很实用：WooCommerce 产品卡片、表单集成、SEO 集成、会员组件、预订小组件，或与第三方插件绑定的管理后台 UI。

### 编辑器策略

`blockstudio.json` 文件也逐渐成为更实用的项目级编辑器策略文件。

7.3 新增了由 PHP 支持的 `blockEditor` 策略层，用于配置 WordPress 已通过服务器端钩子开放的设置。这样，你可以定义全局插入器、样板和媒体行为，无需编写一次性主题粘合代码。

```json title="blockstudio.json"
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockEditor": {
    "blocks": {
      "allow": ["core/*", "my-theme/*"],
      "deny": ["core/embed", "core/freeform"],
      "directory": false,
      "categories": {
        "rename": {
          "text": "Writing",
          "design": "Layout"
        },
        "order": ["my-theme", "text", "media"]
      }
    },
    "patterns": {
      "core": false,
      "remote": false,
      "categories": {
        "deny": ["gallery"],
        "order": ["featured", "buttons"]
      }
    },
    "media": {
      "openverse": false,
      "imageSizes": {
        "allow": ["thumbnail", "large"]
      }
    }
  }
}
```

首个版本特意只涵盖由 PHP 支持的内容：允许和禁止的区块、区块目录加载、插入器分类标签与顺序、样板来源和分类、Openverse、图像尺寸选项、旧版小工具的可见性，以及移除由 PHP 注册的区块样式。

它不会尝试重写任意核心区块默认值。像 `core/columns.isStackedOnMobile` 这样的设置位于区块编辑器的 JavaScript 注册流程中，因此需要通过单独且明确的 API 来配置，而不是假装能将其写进 JSON 文件。

### 区块标签别名

区块标签新增了一个别名过滤器：

```php title="functions.php"
add_filter('blockstudio/block_tags/tag_aliases', function ($aliases) {
    $aliases['theme-button'] = 'bsui/button';
    return $aliases;
});
```

这样，项目就可以定义便于编写的标签，同时在内部仍解析为规范区块名称。

```html
<bs:theme-button label="Continue" />
```

这对于 UI 密集型模板尤其有用：规范区块名称虽然正确，却不一定最适合编写。

## 工具与可靠性

静态分析、可靠性和性能工具都得到了改进。

### 静态分析与生成的文档

PHPStan 扩展新增了对明确指定外部区块库扫描根目录的支持。这意味着项目可以针对当前插件或主题之外的区块验证 `<bs:*>` 和 `<block>` 标签，同时仅将这些根目录用于分析时的注册表。

架构检查也扩展到了页面元数据和 `pluginDependencies`，因此更容易在无效配置进入 WordPress 之前，于发布时将其捕获。

文档生成现在会包含设置和 PHP 钩子的过滤器参考。随着 `blockstudio.json` 从零散的几个开关发展为真正的项目策略文件，这一点变得更加重要。

### 页面和编辑器可靠性

7.3 还包含一系列针对基于文件的页面、编辑器渲染和重置模式的修复。

基于文件的页面解析现在会在解析 HTML 时处理带属性的自定义容器映射。`bs:` 页面标签也能正确解析带连字符的区块命名空间，因此像 `custom-theme/card` 这样的名称不会再让解析器出错。

通用的非核心容器标签在未提供包装标记时，现在也会序列化出有效的 `innerContent`。这让同步后的页面内容更可预测，也能确保 WordPress 区块序列化有效。

编辑器针对预览和预加载行为进行了一系列修复：

- Tailwind 编辑器 CSS 现在会纳入基于文件的页面模板中的 class 候选项。
- 编辑器预加载会为同类型的重复区块保留 RichText 包装类。
- 编辑器预加载现在可以匹配默认字段值经 Gutenberg 展开、但未写入已保存区块标记的区块。
- 比较渲染缓存键之前，会忽略经 Gutenberg 展开的已注册默认属性。
- 即使编辑器和插入器的预览渲染共用同一个 client id，也会保留各自独立的缓存条目。
- `bs_get_group()` 现在能正确处理重复使用的自定义字段组，包括 id 与自定义字段名称相同的组，并且只提取完全匹配的组前缀。
- 带有 `withCreateSuggestion` 的链接字段现在可以正确连接 WordPress LinkControl 创建流程，并通过 REST API 创建草稿页面。
- PHP 区块模板现在每次渲染只执行一次，不再运行后续会被丢弃的预检 include。

重置模式也得到了完善。对于已配置的文章类型，它现在会清除 Gutenberg 编辑器区块的宽度和垂直外边距规则，在需要时移除 WordPress iframe 内容和重置样式，并让 Blockstudio 的悬停和选择覆盖层更整洁。

复杂 InnerBlocks 模式的回归测试范围也扩大了，加入了嵌套的 Blockstudio 区块，以便检查编辑器渲染流程是否能正确处理那些最难手动发现的问题模式插入场景。

### 性能工具

本地匿名 `blockstudio-perf=1` 探测现在可以输出 `Server-Timing` 标头，而不会注入调试面板。

计时范围也涵盖了更多构建生命周期环节：发现、资源处理、注册和覆盖。这样无需启用可见的性能分析 UI，也能更轻松地看出时间实际花在了哪里。

## 此版本为何重要

7.3 的主题是组合。

UI 组件让应用界面的组合更轻松。扩展后的编辑器让大型区块更容易编辑。插件依赖项让区块能够声明所需的插件上下文。编辑器策略将项目级区块编辑器规则移入 `blockstudio.json`。区块标签别名让模板编写更顺手。解析器、PHPStan 和编辑器修复，则让这些组合在经过 WordPress 时更加可靠。

Blockstudio 仍然基于文件。区块仍然是文件夹。模板仍然负责实际工作。但现在，这个框架在此基础上增加了更强大的 UI 层。
