
Blockstudio 7.1 是 v7 重写后的首个功能版本。v7重建了基础，而 7.1 则添加了让区块更进一步的功能：数据库层、服务器函数、定时任务以及 CLI。现在，一个区块目录就可以成为完整的应用程序。

以下是所有新增内容。

## 组件

编辑者在插入器中使用的区块，与开发者用作其他事物构建基础的区块之间，一直存在着矛盾。卡片、徽章、统计小组件、表单输入框都需要完整的 Blockstudio 流程（属性、模板、资源、Tailwind），但根本不该出现在插入器中。

7.1 引入了组件来解决这个问题。在你的 block.json 中设置 `"component": true` 后，该区块会经过完整的构建流程，但不会注册到 WordPress 的区块类型注册表中。它不会出现在插入器中，也不会出现在发送给 JavaScript 的编辑器数据中，但可以通过程序完整地渲染。

```json title="block.json"
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "component": true,
    "attributes": [
      { "id": "title", "type": "text" },
      { "id": "description", "type": "textarea" }
    ]
  }
}
```

从 PHP 渲染：

```php
bs_render_block([
  'name' => 'my-theme/card',
  'data' => ['title' => 'My Card', 'description' => 'Card content.'],
]);
```

或者使用新的 HTML 标签语法：

```html
<bs:my-theme-card title="My Card" description="Card content." />
```

## 区块标签

现在可以使用 HTML 标签嵌入区块，支持两种可互换的语法：

```html
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
```

两种写法都会生成相同的输出。两者都适用于 Blockstudio 区块和核心 WordPress 区块。在区块模板中，它们会自动渲染，无需启用任何选项。这意味着你可以直接在模板中组合其他区块，构建完整的布局：

```twig title="index.twig"
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-heading level="2">Section Title</bs:core-heading>
  <block name="core/group">
    <block name="core/paragraph">Inside a core group block.</block>
    <bs:mytheme-cta variant="primary" />
  </block>
</div>
```

两种语法可以自由嵌套。Blockstudio 区块会经过完整的流程（模板、Tailwind、资源）。核心区块则通过 WordPress，使用为[页面和模式](https://blockstudio.dev/zh/docs/pages-and-patterns/)提供支持的同一套渲染器进行渲染。

对于页面级渲染（文章内容、小组件区域），请在 `blockstudio.json` 中启用：

```json
{ "blockTags": { "enabled": true } }
```

允许列表和拒绝列表通过通配符模式控制哪些区块可以通过标签渲染。`data-*` 和 `html-*` 属性会传递给渲染后区块的根 HTML 元素。可以通过 `blockstudio/block_tags/renderers` 过滤器注册自定义渲染器。

标签解析器采用了新的轻量级字符串扫描器，完全取代了 DOMDocument。它通过深度跟踪处理嵌套标签、递归容器区块和单次扫描中的混合语法。在基准测试中，它能在 2.4ms 内解析 1,000 个扁平标签，在 3.7ms 内解析 100 层嵌套，始终快于 DOMDocument 和 WordPress 的 `WP_HTML_Tag_Processor`。同一解析器还负责解析 [页面和模式](https://blockstudio.dev/zh/docs/pages-and-patterns/)中的原始 HTML 元素，取代了此前用于处理 `<p>`、`<div>` 及其他 HTML 元素的基于 DOMDocument 的解析器。

## 新字段类型

### 区块

一种新的 `block` 字段类型，可将另一个 Blockstudio 区块作为属性引用。被引用区块的字段会通过 `idStructure` 和 `overrides` 内联展开，与自定义字段完全相同。不同之处在于，在模板中访问该值时会返回渲染后的区块输出。

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "card",
        "type": "block",
        "block": "mytheme/card",
        "idStructure": "card_{id}"
      }
    ]
  }
}
```

如果 `mytheme/card` 有 `heading` 和 `content` 字段，宿主区块的侧边栏中就会显示 `card_heading` 和 `card_content`。在模板中，`{{ a.card }}` 会输出渲染后的卡片。普通区块和组件都适用。

### HTML 标签

每个主题中都有一些区块，其标题级别应根据上下文变化：主页上使用 H1，内页上使用 H2。现在有了专用的 `html-tag` 字段类型，并内置预设，无需每次都将其构建为带硬编码选项的选择字段。

```json
{
  "id": "tag",
  "type": "html-tag",
  "default": "h2",
  "tags": "heading",
  "exclude": ["h5", "h6"]
}
```

预设：`heading`（h1-h6）、`text`（标题以及 p、span、div）、`structural`（div、section、article、aside、main、header、footer、nav）、`all`。也可以传入自定义数组。`exclude` 可从任何预设中移除指定标签。

```twig
<{{ a.tag }}>{{ a.title }}</{{ a.tag }}>
```

## 数据库

这是此版本的核心内容。在任意区块目录中添加一个 `db.php` 文件，Blockstudio 就会生成五个 REST CRUD 端点，根据架构验证每次写入，自动管理存储后端，并同时提供 JavaScript 客户端（`bs.db()`）和 PHP API（`Db::get()`）。无需迁移文件、控制器类或路由注册。

```php title="db.php"
return [
    'subscribers' => [
        'storage'    => 'table',
        'capability' => [
            'create' => true,
            'read'   => true,
            'update' => 'edit_posts',
            'delete' => 'manage_options',
        ],
        'fields' => [
            'email' => [
                'type'     => 'string',
                'format'   => 'email',
                'required' => true,
                'validate' => function ($value) {
                    if (str_ends_with($value, '@spam.com')) {
                        return 'This domain is blocked.';
                    }
                    return true;
                },
            ],
            'name' => ['type' => 'string', 'maxLength' => 100],
            'plan' => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
];
```

仅凭这个架构，就能生成一个功能齐全的 API，包含创建、列表、获取、更新和删除端点，且都带有输入验证。

### 存储

提供五种存储后端，分别适用于不同场景：

- **`table`**：通过 `dbDelta()` 管理的自定义 MySQL 表。向架构中添加字段后，下次加载页面时会添加相应列。生产环境的默认选项。
- **`sqlite`**：区块的 `db/` 文件夹中只有一个 SQLite 文件。支持真正的 SQL 查询、使用 WAL 模式支持并发读取，且完全可移植。复制文件夹即可复制数据库。
- **`jsonc`**：每行在一个普通文件中存储一个 JSON 对象。易读、可进行版本控制，并对 git 友好。
- **`meta`**：将 JSON 数组存储在 WordPress 文章元数据中，并关联到特定文章。
- **`post_type`**：每条记录都会成为自定义文章类型中的一篇 WordPress 文章。字段分别存储为独立的文章元数据条目，可通过 `WP_Query` 完整查询。

### 客户端

在 JavaScript 端，`bs.db()` 为你提供完整的 CRUD 客户端：

```js
const db = bs.db('my-theme/block', 'subscribers');
const record = await db.create({ email: 'a@b.com', plan: 'pro' });
const pros = await db.list({ plan: 'pro' });
await db.update(record.id, { plan: 'free' });
await db.delete(record.id);
```

此外还附带三个配套工具：

- **`bs.cache`**：内存查询缓存，支持 `get`、`set`、`invalidate` 和 `clear`。所有查询和变更调用共享此缓存。
- **`bs.query(key, fn, options)`**：为任意异步函数添加缓存、请求去重和可配置的 `staleTime`。请求进行中时，使用相同键发起的多个调用会返回同一个 promise。
- **`bs.mutate(options)`**：处理乐观变更，并自动回滚。传入响应式状态对象、一个操作（`create`、`update`、`delete`）和乐观数据。UI 会立即更新。如果服务器调用失败，状态就会回滚到变更前的快照。

这些工具共同覆盖完整的读写周期：`bs.query` 用于缓存读取，`bs.mutate` 用于乐观写入，`bs.cache` 用于手动控制。

在 PHP 端，`Db` 类提供相同的操作：

```php
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');
$db->create(['email' => 'a@b.com', 'plan' => 'pro']);
$db->list(['plan' => 'pro']);
```

### 验证

验证错误会以按字段分组的错误数组形式返回，格式参考 Zod 的 `fieldErrors`。同一字段可以有多条规则验证失败，这种结构便于在前端将错误对应到表单字段：

```json
{
  "data": {
    "status": 400,
    "errors": {
      "email": ["Must be a valid email address.", "This domain is blocked."],
      "plan": ["Must be one of: free, pro."]
    }
  }
}
```

对于内置规则无法覆盖的情况，可以使用自定义 `validate` 回调在服务器端执行验证，例如屏蔽域名、跨字段验证和外部查询。

### 用户范围数据

对于待办事项、收藏或草稿等按用户区分的数据，将 `userScoped` 设为 `true`，剩下的交给 Blockstudio 处理。它会添加 `user_id` 列，在创建时自动设置该列，并将所有查询限制为当前用户的数据。更新和删除操作都会检查所有权。无需手动添加 `user_id` 字段、`before_create` 钩子，也无需在 RPC 中进行筛选。只需一行配置。使用 `post_type` 存储时，`userScoped` 会映射到 `post_author`，而非单独的列。

```php
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [ /* ... */ ],
];
```

### 实时轮询

在架构中设置 `'realtime' => true`，客户端就会自动轮询以检查变化。当服务器上的内容发生变化时，Interactivity API 存储会更新，UI 也会重新渲染，你无需更改 JavaScript。使用 `'realtime' => ['key' => 'todos', 'interval' => 5000]` 配置自定义状态键和轮询间隔。轮询通过哈希比较减少请求开销，并会在浏览器标签页隐藏时暂停。

### 安全、钩子与可移植性

公共端点会自动注入 `X-BS-Token` CSRF 标头进行保护。需要完全匿名访问时（例如接收传入的 Webhook），请使用 `'open'`。

每次写入操作前后都会触发生命周期钩子。可在 `db.php` 中内联定义，也可通过 WordPress 操作全局定义。

字段可以定义一个 `component` 键，以便通过 `bs_db_form()` 根据架构渲染表单。

使用 SQLite 或 JSONC 存储时，整个应用都位于同一个文件夹中：代码、逻辑、访问控制和数据。复制该文件夹即可部署。

## RPC

有时 CRUD 并不足够。你可能需要自定义服务器逻辑，例如切换待办事项状态、发送通知或汇总统计数据。这正是 `rpc.php` 的用途。定义一个 PHP 函数，在前端通过 `bs.fn()` 调用它，Blockstudio 就会处理 REST 端点、身份验证、CSRF 保护和 JSON 序列化。这种模式参考了 [tRPC](https://trpc.io)：在服务器端定义过程，然后由客户端按名称调用。

```php title="rpc.php"
return [
    'subscribe' => function (array $params): array {
        $email = sanitize_email($params['email']);
        return ['success' => true];
    },
];
```

```js
const result = await bs.fn('subscribe', { email: 'user@example.com' });
```

内联脚本（`script-inline.js`）会自动从脚本标签上的 `data-block` 属性识别区块名称，因此无需手动传入。模块脚本则将其作为第三个参数传入。

访问控制选项包括 `public`（带 CSRF 保护）、`'open'`（无保护）、权限字符串或数组。支持按函数设置 HTTP 方法控制、生命周期钩子，以及从 JS 和 PHP 跨区块调用。

## Cron

在 `cron.php` 文件中定义后台任务。设置计划和回调后，Blockstudio 会在初始化时通过 WordPress Cron 注册任务。停用插件时，所有任务都会妥善取消计划。

```php title="cron.php"
return [
    'cleanup' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db = Db::get('my-theme/app', 'logs');
            // delete old entries
        },
    ],
    'sync' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // pull from external API
        },
    ],
];
```

支持所有内置 WordPress 计划，也可通过 `cron_schedules` 过滤器设置自定义间隔。

## CLI

新增 `wp bs` 命令，涵盖完整的 Blockstudio 功能集：区块、数据库、RPC、cron、设置、Tailwind 编译、SCSS 编译、自定义字段和资源管理。

```bash
wp bs blocks list --components
wp bs db schemas
wp bs db create my-theme/app subs --email=a@b.com
wp bs db list my-theme/app subs --plan=pro --format=json
wp bs rpc call my-theme/app subscribe --email=a@b.com
wp bs cron run my-theme/app cleanup
wp bs tailwind compile --file=template.html
wp bs scss compile --file=style.scss
wp bs fields list
wp bs assets list --type=global
wp bs settings get tailwind/enabled
```

所有命令都支持 `--format=json`，便于编写脚本。

## Repeater 改进

### 对象字段的 textMinimized

现在，折叠的 Repeater 行可以正确处理对象字段值。以前，将 `textMinimized` 指向链接字段时会显示 `[object Object]`。现在，Blockstudio 会根据字段类型自动读取正确的子属性：链接读取 `title`，颜色和渐变读取 `value`，图标读取 `icon`。你也可以显式设置 `key` 属性，读取所需的任意子属性。

```json
{
  "type": "repeater",
  "textMinimized": { "id": "href", "fallback": "Add a link" },
  "attributes": [{ "id": "href", "type": "link" }]
}
```

### RichText 和 MediaPlaceholder

现在，这两个模板组件都能在 Repeater 字段中使用方括号表示法，以指定正确的行。可以在 Repeater 的每一行中内联编辑标题和段落，也可以上传媒体。

```twig
{% for item in a.items %}
  <div class="card">
    <MediaPlaceholder attribute="items[{{ loop.index0 }}].image" />
    <RichText tag="h2" attribute="items[{{ loop.index0 }}].heading" />
    <RichText tag="p" attribute="items[{{ loop.index0 }}].content" />
  </div>
{% endfor %}
```

## 使用 idStructure 设置自定义字段条件

使用带有 `idStructure` 的自定义字段时，字段定义中的条件现在会自动重写其 ID，以匹配展开后的名称。如果你的 font-size 字段组中有一项条件针对 `enable`，并通过 `idStructure: "title_font_{id}"` 展开该字段组，现在条件会正确引用 `title_font_enable`，而非原来的 `enable`。

也支持引用级别的条件。在自定义字段引用上添加 `conditions`，即可一次性将条件应用到所有展开的字段。

## 动态填充参数

现在，填充参数可以使用 `{attributes.*}` 语法引用其他区块属性。被引用的属性发生变化时，选择字段会自动重新获取选项。你可以将多个选择字段串联起来：一个用于选择文章类型，另一个则加载该类型的文章。

```json
{
  "id": "selected_post",
  "type": "select",
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "{attributes.post_type}"
    }
  }
}
```

将 `post_type` 改为 “page”，第二个选择字段就会加载页面；改为 “post”，它就会加载文章。适用于任何填充类型和任何属性。

## Composer

从 `wp-content/` 下的任何位置加载时，Blockstudio 现在都能正常工作，不再局限于插件目录。资源 URL 通过 `BLOCKSTUDIO_URL` 常量解析，而非 `plugins_url()`，因此主题内置安装开箱即用：

```php title="functions.php"
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/vendor/blockstudio/blockstudio/blockstudio.php';
```

已清理 `composer.json` 的运行时依赖。已捆绑在 `lib/` 中的作用域包（TailwindPHP、ScssPhp、Minify）不再列为运行时依赖。现在只剩下 `php >= 8.2` 和 `plugin-update-checker`。

三种安装方式（插件 zip、通过 Composer 安装插件、通过 Composer 将其内置于主题）启动后效果相同：完整激活 WordPress、注册区块并渲染前端。

请参阅 [Composer 文档](https://blockstudio.dev/zh/docs/dev/composer/)，了解设置说明。

## 性能分析器

在任意页面 URL 中添加 `?blockstudio-perf`，页面底部就会出现调试面板，显示各区块的渲染时间、各阶段的耗时细分以及缓存命中率。计时数据也会通过 Server-Timing 标头发送，可在浏览器 DevTools 的 Network 标签页中查看。

```json title="blockstudio.json"
{ "dev": { "perf": true } }
```

在设置中永久启用后，即可分析每次页面加载。只有具备 `edit_posts` 权限的登录用户才能看到。

现在，自闭合区块标签也会缓存在内存中。当同一区块及相同属性在页面中多次出现时，后续渲染会跳过整个模板流程。

## 错误修复

- **PHP 8.4 弃用警告**：修复了传递 `null` 给 `add_submenu_page()` 导致的 `strpos()` 和 `str_replace()` 弃用警告。

## 更多内容

- **SCSS 代码字段**：代码字段现在支持 `language: "scss"`。在编辑器和前端，值都会通过 ScssPhp 编译。
- **标准 WordPress 区块**：Blockstudio 目录可以包含 Blockstudio 区块之外的 `@wordpress/create-block` 输出。系统会自动注册这些内容，无需单独编写插件代码。

---

如果你想了解全栈模式的实际应用，[全栈区块指南](https://blockstudio.dev/zh/guides/full-stack-blocks/)会从头讲解如何构建按用户区分的待办应用，以及公开的新闻简报订阅表单。
