
Blockstudio 7 发布了。这是该项目历史上规模最大的一次发布：整个代码库从头全面重写。每个类、每个钩子、每行代码都经过重建，致力于采用现代 PHP、WordPress 编码规范，并确保长期可维护性。

但这不只是一次重构。Blockstudio 7 引入了多项重要新功能，例如基于文件的页面和区块模式、文章元数据存储系统、SEO集成，以及为所有功能提供支持的全新 HTML到区块解析器。此外，Blockstudio 现已完全免费开源。

下面来详细了解所有新功能。

## 免费开源

自 2020 起，我一直在开发 Blockstudio，这些年来发布了数十个版本。用户很喜欢它，但商业化的 WordPress 区块框架始终难以找到合适的市场定位。

改变局面的是 LLM。AI 编码助手如今已经足以编写区块代码，但它们需要结构清晰、基于文件的内容来处理。WordPress 区块标记很杂乱：序列化的 HTML 注释中嵌入了 JSON 属性，还混杂着 DOM 结构。这对人类来说很难处理，对 LLM 来说更难正确生成。

Blockstudio 始终采用文件优先的方式来保持简洁：一个目录中放一个 `block.json` 和一个 PHP 模板。不需要数据库条目，不需要 React，也不需要构建步骤。借助 v7，这一理念得以进一步延伸。HTML到区块解析器可以让你编写纯 HTML，并自动将其转换为有效的区块标记。所有内容都保留在文件系统中。只有通过 PHP API 或 CLI 明确请求页面同步时，才会写入数据库；而同步内容由文件模板驱动。

将 Blockstudio 开源是顺理成章的下一步。LLM 训练的 Blockstudio 代码越多，生成代码的能力就越强。开放的代码库、开放的文档，以及任何工具都能读取的预构建[AI 上下文文件](https://blockstudio.dev/zh/docs/dev/ai/)，这正是打造最佳 AI 辅助 WordPress开发环境的方式。

完整插件现已发布在[GitHub](https://github.com/inline0/blockstudio)，任何人都可以使用、派生和参与贡献。无需许可证密钥，没有付费墙，也没有功能限制。

## 新功能

### 基于文件的页面

这是 7.0 中最重要的新增功能之一。现在，你可以将整个 WordPress 页面定义为文件模板；调用页面同步 API 或 CLI 时，模板会以原生区块内容的形式同步到数据库。

创建一个包含 `page.json` 和模板文件的文件夹：

```json title="page.json"
{
  "name": "about",
  "title": "About Us",
  "slug": "about",
  "postStatus": "publish"
}
```

```php title="index.php"
<div class="about-page">
  <h1>About Us</h1>
  <p>Welcome to our site.</p>
</div>
```

运行 `wp bs pages sync`，让 Blockstudio 将 HTML 解析为 WordPress 区块，并在数据库中创建或更新页面。

#### 按键合并区块

模板同步时，用户的编辑通常会被覆盖。`key` 属性通过在同步期间保留用户内容解决了这个问题：

```html title="index.php"
<h1 key="hero-title">Default Title</h1>
<p key="hero-description">Default description.</p>
```

键匹配的区块在模板更新时会保留用户编辑的内容。没有键的区块则会被完全替换。

#### 区块绑定

除了使用键，你还可以使用 WordPress 核心的[区块绑定API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-bindings/)，将区块直接连接到文章元数据。这不是 Blockstudio 功能，而是原生 WordPress API。Blockstudio 只需将 `metadata` 属性传递给生成的区块标记。内容存储在元数据中，而非区块标记中，因此模板同步不会破坏用户的编辑。还可以通过 `WP_Query` 查询数据，并通过 REST API 使用数据。

```html title="index.php"
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
  Default Title
</h1>
```

这两种方式可以在同一个模板中使用。

#### 编辑控制

页面支持 `blockEditingMode` 和 `templateLock`，用于控制用户可以修改的内容：

```json title="page.json"
{
  "name": "landing",
  "title": "Landing Page",
  "blockEditingMode": "contentOnly",
  "templateLock": "all"
}
```

这样可以锁定页面结构，同时仍允许用户编辑文本和媒体。模板中的 `blockEditingMode` 属性可以覆盖页面级设置，应用于单个元素。

#### 固定到文章 ID

使用 `postId` 将页面模板绑定到现有的 WordPress 文章，以防止页面重复，并确保模板始终更新正确的文章：

```json title="page.json"
{
  "name": "home",
  "title": "Home",
  "postId": 2
}
```

详情请参阅[页面文档](https://blockstudio.dev/zh/docs/pages-and-patterns/pages/)。

### 基于文件的区块模式

与页面类似，现在你也可以将区块模式定义为文件模板。用 HTML 编写模式，Blockstudio 会将其解析为区块标记，并注册为原生 WordPress 区块模式。它们会显示在区块插入器中，用户可以将其放置在任意位置。

```json title="pattern.json"
{
  "name": "hero-section",
  "title": "Hero Section",
  "categories": ["featured"],
  "keywords": ["hero", "banner"]
}
```

```html title="index.php"
<div class="hero">
  <h1>Welcome</h1>
  <p>Get started today.</p>
</div>
```

与页面不同，区块模式不会创建数据库条目。每次加载页面时，它们都会在内存中注册。请参阅[区块模式文档](https://blockstudio.dev/zh/docs/pages-and-patterns/patterns/)。

### HTML到区块解析器

页面和区块模式都由全新的 HTML 解析器驱动，可将标准 HTML 模板转换为 WordPress 区块标记。它会自动处理容器区块（例如组和栏）以及叶区块（例如段落和标题）。解析器采用基于 trait 的渲染器架构，可通过 `blockstudio/parser/renderers` 筛选器轻松扩展，以支持其他区块类型：

```php title="functions.php"
add_filter( 'blockstudio/parser/renderers', function ( $renderers, $parser ) {
    $renderers['acme/hero'] = function ( $element, $attrs, $parser ) {
        $content = $parser->get_inner_html( $element );
        $html    = '<div class="acme-hero">' . $content . '</div>';

        return array(
            'blockName'    => 'acme/hero',
            'attrs'        => $attrs,
            'innerBlocks'  => array(),
            'innerHTML'    => $html,
            'innerContent' => array( $html ),
        );
    };

    return $renderers;
}, 10, 2 );
```

注册后，你就可以在任何页面或区块模式模板中使用该区块：

```html title="index.php"
<block name="acme/hero" background="/hero.jpg">
  <h1>Welcome to our site</h1>
</block>
```

### 存储

现在，除了区块属性之外，字段值还可以存储在文章元数据或站点选项中。这是一项重要功能：

```json title="block.json"
{
  "id": "subtitle",
  "type": "text",
  "label": "Subtitle",
  "storage": {
    "type": "postMeta"
  }
}
```

将值存储在文章元数据中后，你可以：

- 使用 `WP_Query` 和 `meta_query` 按字段值查询文章
- 在无头架构中，通过 REST API 访问字段数据
- 与其他插件（例如 SEO 工具）和缓存层共享数据

你也可以将值存储在选项表中，用于全局的站点级设置：

```json title="block.json"
{
  "id": "phone",
  "type": "text",
  "label": "Phone Number",
  "storage": {
    "type": "option",
    "optionKey": "company_phone"
  }
}
```

完整[存储文档](https://blockstudio.dev/zh/docs/blocks/storage/)请参阅API。

### 自定义字段

现在可以在多个区块之间共享可复用的字段定义。只需定义一次字段集，即可在任何区块中引用。这样，当多个区块使用相同的字段结构时，就不必重复定义。

在你的 blockstudio 目录中创建一个 `field.json`：

```json title="fields/hero/field.json"
{
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    { "id": "heading", "type": "text", "label": "Heading", "default": "Hello World" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
```

然后使用 `custom/` 前缀，在任意区块中引用它：

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/hero", "idStructure": "hero_{id}" }
    ]
  }
}
```

`idStructure` 属性会为每个字段 ID 添加前缀，因此 `heading` 会变为 `hero_heading`。你也可以使用 `overrides` 键按实例覆盖单个字段属性。

请参阅[自定义字段文档](https://blockstudio.dev/zh/docs/blocks/attributes/custom-fields/)。

### Tailwind CSS v4

Tailwind 支持已针对 v4 全面重建。以往采用 CDN 在客户端编译，并在文章保存时写入磁盘（即 v6 方式）；Blockstudio 7 则会在每次前端请求时，通过 [TailwindPHP](https://github.com/dnnsjsk/tailwindphp) 在服务器端编译 Tailwind。无需 Node.js，无需 CLI，也无需构建步骤。

编译采用基于候选项的缓存：Blockstudio 从最终的 HTML 中提取所有 CSS 类名，将它们排序并与 CSS 配置一起计算哈希，然后检查缓存文件。即使外围的 HTML 发生变化（例如 nonce、时间戳、动态内容），相同的类仍会命中同一缓存。

配置使用 Tailwind v4 的 CSS 优先语法。可直接在 `blockstudio.json` 中定义自定义主题和实用类，也可以通过 `blockstudio/tailwind/css` 筛选器定义：

```php title="functions.php"
add_filter('blockstudio/tailwind/css', function ($css) {
  return $css . '
    @theme {
      --color-brand: #4f46e5;
    }

    @layer utilities {
      .container-narrow {
        max-width: 48rem;
        margin-inline: auto;
      }
    }
  ';
});
```

在区块编辑器中，内置的 Tailwind CDN 脚本会在输入时提供实时预览。`classes` 字段类型可为所有 Tailwind 实用类提供自动补全。前端始终使用服务器编译的 CSS，并将其作为内联样式标签注入到 `</head>` 之前。

完整设置说明请参阅[Tailwind 文档](https://blockstudio.dev/zh/docs/tailwind/)。

### 交互性 API

Blockstudio 现已支持[WordPress 交互性 API](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/)。在你的 block.json 中启用：

```json title="block.json"
{
  "blockstudio": {
    "interactivity": true
  }
}
```

向模板添加 `data-wp-*` 指令：

```php title="index.php"
<div useBlockProps
     data-wp-interactive="myBlock"
     data-wp-context='{ "isOpen": false }'>
  <button data-wp-on--click="actions.toggle"
          data-wp-bind--aria-expanded="context.isOpen">
    Toggle
  </button>
  <div data-wp-bind--hidden="!context.isOpen">
    This content is toggled by the button.
  </div>
</div>
```

然后创建一个 `script.js`，编写存储逻辑：

```javascript title="script.js"
import { store, getContext } from '@wordpress/interactivity';

store('myBlock', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});
```

Blockstudio 会在前端和区块编辑器中处理导入映射表、模块加载和指令处理。仅使用声明式指令和 `data-wp-context`（例如 `data-wp-bind--hidden` 或 `data-wp-text`）的区块完全不需要 JavaScript。前端也支持通过 `wp_interactivity_state()` 使用服务器端状态。

完整设置说明请参阅[交互性文档](https://blockstudio.dev/zh/docs/blocks/interactivity/)。

### SEO 内容分析

Blockstudio 区块是动态的，因此默认情况下，SEO 插件无法看到其中的字段内容。Blockstudio 7 通过自动集成 Yoast SEO、Rank Math 和 SEOPress 解决了这一问题。系统会提取 `text`、`textarea`、`richtext`、`wysiwyg` 和 `link` 字段中的文本值（包括嵌套的重复器行），并将其提供给各插件进行内容分析。现在，SEO 插件可以正确分析区块内容的关键词密度、可读性和其他指标。无需配置。

### 重复器默认行

重复器字段现在支持 `default` 属性，可为行预先填入数组。插入区块时，重复器会在编辑器和前端中填入指定的行及其值：

```json title="block.json"
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "default": [
    { "title": "Fast", "icon": "bolt" },
    { "title": "Secure", "icon": "shield" }
  ],
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    { "id": "icon", "type": "text", "label": "Icon" }
  ]
}
```

`min` 属性也适用于字段级默认值：如果重复器具有 `min: 3`，且其内部字段设有 `default` 值，自动生成的行就会预先填入这些默认值，而不会留空。

## 改进和修复

- **带字段默认值的重复器 `min`**：自动生成的最小行数现在会在前端和编辑器中使用字段级默认值
- **Tailwind 编辑器样式**：编译后的 Tailwind CSS 现在会与 CDN 一同注入区块编辑器 iframe，因此自定义 `@apply` 规则和主题配置在编辑器中也能生效
- **[AI 上下文文件](https://blockstudio.dev/zh/docs/dev/ai/)**：`blockstudio-llm.txt` 已重建为静态文件，由完整的 v7 文档和去重后的 JSON 架构（约 48k tokens）汇编而成，取代了从 v6 动态生成的方式
- **代码字段弹出窗口**：现在可以在独立窗口中打开代码字段，并提供独立的撤消/重做和 JavaScript 语法高亮
- **Tailwind v4 服务器端编译**：请参阅上文的[Tailwind相关章节](#tailwind-css-v4)
- **API 第 3 版**：区块现在可以在 iframe 编辑器中正确渲染，包括站点编辑器和响应式预览
- **资源的点号表示法**：资源后缀使用更简洁的文件命名约定（`*.inline.css`、`*.editor.js`、`*.scoped.css`）
- 修复了使用 `useBlockProps` 时 `WP_Block_Supports` 中的 `bs_render_block()` 警告
- 修复了条件字段在首次加载时不遵循默认值的问题
- 修复了前端内容中的美元符号被删除的问题：`<RichText />`
- 修复了 `populate` 功能，使其适用于其他插件注册的分类法
- 修复了 WPML 上下文中的 `optionsPopulate` 空值错误

## 内部实现

### 全面重写

这不是一次重构或代码清理。每个类都从头重写。最终代码库更加简洁、模块化，也更易于维护和扩展。

### 现代 PHP

Blockstudio 7 要求 PHP 8.2+，并全面使用现代类型声明。

## 重大变更

作为一次主要版本更新，7.0 包含多项重大变更。大多数变更都提供向后兼容的回退方案，但升级前仍应仔细查看。完整迁移指南请参阅[v7迁移文档](https://blockstudio.dev/zh/docs/dev/migration/v7/)。

### 钩子名称现在使用 snake_case

所有 PHP 钩子都已从 camelCase 重命名为 snake_case，以符合 WordPress 核心约定：

```php title="functions.php"
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
    return ['my-stylesheet'];
});

// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
    return ['my-stylesheet'];
});
```

旧的 camelCase 名称仍然可用，但我们建议进行更新。

### 字段开关默认关闭

`switch` 属性现在默认设置为 `false`，而不是 `true`。在 v6 中，每个字段左侧边缘都有一个默认启用且不可见的切换开关。在 v7 中，开关改为默认关闭，并在字段标签中使用可见的眼睛图标。如果你依赖默认开关行为，请在字段定义中添加 `"switch": true`。

### 资源文件名使用点号表示法

资源后缀现在使用点号而非连字符（`style.inline.css` 而非 `style-inline.css`）。旧的连字符写法仍然可用，但今后建议使用点号写法。

### npm 导入前缀

ES 模块导入现在使用 `npm:`，而不是 `blockstudio/`：

```javascript title="script.js"
// Before (v6)
import confetti from "blockstudio/canvas-confetti@1.6.0";

// After (v7)
import confetti from "npm:canvas-confetti@1.6.0";
```

为保持向后兼容，仍支持 `blockstudio/` 前缀。

### 已移除的功能

**管理区域和代码编辑器。** WordPress 管理设置页面和内置区块代码编辑器均已移除。现在所有配置都通过 `blockstudio.json` 和 PHP 筛选器完成，这意味着配置会与区块一同保存在版本控制中。

早期版本中的代码编辑器可用于预览区块，但始终无法完全匹配真正的开发环境。多年来，一些插件功能一直受限，因为它们无法在独立编辑器中实现。它也不可能取代完整的 IDE。移除代码编辑器后，插件可以专注于基于文件的开发，不再受此限制。

**许可证密钥。** 不再需要。Blockstudio 免费开源。

**区块库。** 内置的“Blockstudio Elements”库（图库、滑块、图像对比、代码、图标）已移除。这些是随插件附带的预构建示例区块。如果你正在使用它们，请将区块文件夹从 v6 复制到主题的 blockstudio 目录中。

## 开始使用

安装 Blockstudio 7，几分钟内即可创建第一个区块。请参阅[入门指南](https://blockstudio.dev/zh/docs/general/getting-started/)，按步骤了解操作流程；如果你要从 v6 升级，请参阅[v7迁移指南](https://blockstudio.dev/zh/docs/dev/migration/v7/)。

完整源代码位于[GitHub](https://github.com/inline0/blockstudio)。欢迎提交问题、PR 和反馈。
