
Blockstudio 7.4 旨在让基于文件的项目更易于移植。7.2 让大型项目更容易检查和分发，7.3 在此基础上增加了一个 UI 层，而 7.4 则着重将项目、页面及精选内容的更多部分从数据库移入版本控制的文件。

核心功能是页面集合：通过它，Blockstudio 可以指向一个页面源文件夹，并据此生成完整的嵌套 WordPress 页面结构。页面源可以是 PHP、Twig、Blade、HTML、Markdown，也可以是从其他本地来源返回页面的可信加载器。

简而言之：

- **页面集合**：`pages.json` 可定义完整的嵌套页面集、默认值、文章类型行为、布局、加载器和集合元数据。
- **Markdown 页面**：`index.md` 可作为页面内容，既可以配合 `page.json` 使用，也可以单独配合 frontmatter 使用。
- **前端页面布局**：`layout.php` 可包装同步后的页面内容，并使用 `blockstudio_page_tree()` 和 `blockstudio_page_content()` 等辅助函数。
- **外部文档来源**：集合加载器可根据本地文件或返回的 Markdown/HTML 生成页面。
- **原始 Markdown 输出**：Markdown 页面源可作为 `.md` 提供，也可通过 `Accept: text/markdown` 提供。
- **集合自定义文章类型**：集合可拥有简洁 URL、自动刷新重写规则、原始 Markdown 路由，以及页面迁移到自定义文章类型的功能，无需主题侧的垫片代码。
- **Content Sync**：`wp bs content pull`、`wp bs content push` 和 `wp bs content status` 可将项目允许列表中的文章、术语、关系和已声明的元数据引用保存为可移植文件。
- **区块标签前缀**：项目前缀（例如 `<theme-card>`）可跨有序命名空间解析，无需为每个区块设置别名。
- **更可靠的同步**：可检测清单、加载器、布局、元数据和源文件中的页面变更。
- **运行时和编辑器修复**：动态选项保持最新，查询区块类在程序化渲染时得以保留，`bsui/select` 在密集表单中的表现更好，RichText 属性会传递到编辑器中，且保存后可保留带 RichText 的重复器行删除操作。

## 基于文件的页面

7.4 的大部分功能都建立在基于文件的页面之上。

### 页面集合

在 7.4 之前，基于文件的页面主要是文件夹级功能：创建 `page.json`，添加 `index.php` 或 `index.twig`，然后由 Blockstudio 将单个页面同步到 WordPress。

这种方式仍然可用。7.4 为更大型的结构增加了第二种模式。

在文件夹中添加 `pages.json` 清单，该文件夹就会成为一个集合：

```txt
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
```

```json title="pages/docs/pages.json"
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
```

系统会发现集合中的每个页面源，对其进行规范化和同步，并按路径建立链接。位于 `guide/install` 的页面会成为 `guide` 的子页面；如果缺少 `guide` 页面，Blockstudio 会创建一个生成的容器页面，使 WordPress 层级仍与文件系统结构一致。

集合可以使用原生的 `page` 文章类型，也可以使用自己的文章类型。如果集合声明的文章类型尚不存在，Blockstudio 会根据 `postTypeArgs` 注册该类型。清单中的 `postType` 也会成为集合中每个页面的默认值，因此项目无需在 `defaults` 中重复设置。

集合文章类型使用集合别名作为其公开的 URL 基础路径。`docs` 集合会在 `/docs/` 解析其根页面；带有 `path: "getting-started"` 的页面会在 `/docs/getting-started/` 解析；嵌套路径则使用相同的基础路径。像 `/docs/docs/` 这样的重复 URL 会重定向到规范位置。集合文章类型的路由发生变化时，重写规则会自动刷新，因此新增集合无需手动保存固定链接。

正是这一功能让外部文档、产品手册、知识库和页面库在 WordPress 中显得浑然一体：源文件仍保存在文件中，生成的内容依然是真正可编辑的 WordPress 内容。

### 将 Markdown 用作页面内容

现在，Markdown 已成为一等页面源。

独立的 Markdown 页面使用 frontmatter：

```md title="pages/about/index.md"
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.
```

如果想将配置和内容拆分到不同文件中，也可以将 `page.json` 与 `index.md` 配合使用。`index.md` 中的 Frontmatter 可以覆盖相匹配的 `page.json` 字段，未知的 frontmatter 键则会作为元数据保留。

Markdown 会转换为 HTML，然后与 PHP、Twig 和 Blade 模板一样，经过同一个页面解析器处理，因此最终内容是原生区块标记。

### 布局和页面辅助函数

集合可以包含一个 `layout.php` 文件。在前端，Blockstudio 会使用该布局包装同步后的页面内容。

```php title="pages/docs/layout.php"
<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <a href="<?php echo esc_url($item['permalink'] ?? '#'); ?>">
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>
```

新的辅助函数会将集合作为结构化数据公开：

```php
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
```

这样一来，你就拥有了构建完整文档框架所需的组件：页面树导航、来自 frontmatter 的页面元数据，以及作为主要内容区域的已同步 WordPress 区块内容。

### 加载器和原始 Markdown

集合可以包含可信的本地 `loader.php` 文件。该文件可直接返回页面，也可以让 Blockstudio 查找其他本地目录。

```php title="pages/docs/loader.php"
<?php

return [
  'pages' => [
    [
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ],
  ],
];
```

当来源已经在其他地方生成时，这种方式很有用：例如软件包文档文件夹、Markdown 导出文件，或返回页面列表的构建步骤。

Markdown 页面源也可以提供其原始 Markdown 源码。可在页面 URL 后添加 `.md` 后缀来请求页面，或发送 `Accept: text/markdown`。响应中会移除 Frontmatter，因此工具可以获取可读的文档正文。集合文章类型也支持此功能，包括 `/docs.md` 和 `/docs/getting-started.md` 这样的 URL。

[阅读 Pages 文档](https://blockstudio.dev/zh/docs/pages-and-patterns/pages/)

## 内容同步

7.4 还引入了 Content Sync，这是一种 WP-CLI 工作流，适合希望将更多 WordPress 项目内容保存为文件的团队。

```bash
wp bs content pull
wp bs content push --dry-run
wp bs content status
```

Blockstudio 已将区块、字段、模板、模式和基于文件的页面保存在你的项目中。Content Sync 将选定的数据库内容纳入这一文件优先工作流：允许列表中的文章、术语、关系和已声明的元数据可以导出到文件、在 git 中审核，并推送到其他环境。

它的设计刻意保持明确。你可以在 `blockstudio.json` 中启用此功能，将想要管理的文章类型和分类法加入允许列表，并声明应在不同环境之间重写的元数据引用。

拉取时，Blockstudio 会将可移植文章、术语、关系和允许列表中的元数据写入主题文件。推送时，它会在写入之前验证计划，并将已声明的 `post`、`term` 和 `attachment` 引用解析回本地数据库 ID。它不会臆测任意整数就是 ID。

7.4 的范围经过审慎控制，包含文章、术语、术语关系、允许列表中的元数据、可移植 UID、附件清单、试运行、清理处理、锁定实体和状态报告。此首个版本有意不包含分类法定义捕获、媒体二进制文件复制和区块标记 ID 重写。

这为团队提供了一种简洁的方式，可将团队成员、案例研究、地点、文档条目或其他结构化记录等精选内容纳入版本控制，而无需将整个生产数据库变成迁移对象。此功能适用于仍可作为文件审核的内容集：几十或几百条记录；在某些项目中，如果内容结构清晰且变更少，也可以达到数千条。它不能替代数据库备份，也不适用于电商或订单同步、分析数据、日志、表单提交或其他高容量数据。

[阅读 Content Sync 文档](https://blockstudio.dev/zh/docs/content-sync/)

### 更可靠的同步

Blockstudio 现在会检测页面源、集合清单、加载器文件、布局文件、元数据和相关路径中的变更。只要其中任一项发生变化，已同步的 WordPress 页面就会更新。

页面处理流程也能应对各种细节，让基于文件的文档在真实项目中更实用：

- Markdown 页面源会同步为原生区块内容，包括区块属性
- 前端辅助函数和布局可以使用 Frontmatter 元数据
- 集合页面在多次同步之间保持稳定身份
- 嵌套的非集合页面会链接到其父页面
- 非集合嵌套页面可以继承最近祖先页面的 `layout.php`
- 移除集合源后，会清理其生成的 WordPress 页面
- 将集合从 `page` 更改为自定义文章类型时，会迁移现有同步文章，而不是创建重复项
- 页面顺序会通过 `menu_order` 保存

## 区块标签前缀

区块标签现在支持可配置的命名空间前缀。项目可以注册一个简短前缀，让 Blockstudio 在一个或多个命名空间中解析区块：

```php
add_filter('blockstudio/block_tags/prefixes', function ($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
```

设置完成后，`<theme-card>` 可以解析为 `theme-components/card`，`<theme-button>` 可以回退到 `bsui/button`，`<theme-ui-feature-matrix>` 则可以解析为 `theme-components/ui-feature-matrix`。

项目需要进行一次性覆盖时，显式的 `tag_aliases` 仍然优先。未知的前缀标签会保持原样，现有的区块标签允许和拒绝过滤器仍适用于通过前缀解析的区块。

[阅读区块标签文档](https://blockstudio.dev/zh/docs/blocks/rendering/#prefix-shorthands)

## 运行时和编辑器修复

7.4 还包含一系列根据真实项目使用情况做出的修复。

- 当文章、术语、用户或相关元数据发生变化时，动态查询填充的选项会保持最新；`populate.fetch: true` 查询选择框在编辑器搜索为空时也会获取实时选项。
- 通过程序生成的 `core/query` 和 `core/comments` 区块标签会在生成的包装标记中保留 `className`。
- 模板伪组件会保留 camelCase 属性，因此 `allowedFormats` 和 `withoutInteractiveFormatting` 等属性会传递给编辑器组件，而不会提前被丢弃。
- `bsui/select` 能更可靠地处理选项数据和溢出菜单，在较密集的编辑器控件中尤其如此。
- `blockstudio/phpstan` 可以识别声明在 `tabs` 容器内的字段，因此模板、Twig/Blade 和区块标签验证都能理解项目中 Blockstudio 使用的相同字段结构。
- 删除带有 RichText 的重复器行后，保存时会保留删除结果。过时的 RichText 值不会再让已删除的行恢复。

## 此版本为何重要

7.4 的主题是可移植性。

页面集合可将整个文档网站转换为源文件文件夹。Markdown 页面让这些内容更易于编写和读取。Content Sync 将同样的文件优先模式扩展到精选数据库内容，使文章、术语和关系可以保存在 git 中并在不同环境间迁移。区块标签前缀让大型区块库在模板中更易读。

Blockstudio 仍然基于文件。区块仍然是文件夹。页面仍然是文件。7.4 让项目的更多内容，包括页面结构和精选内容，都能保存在这些文件中并随文件一起迁移。
