跳转到正文

Dennis · 2026年6月21日

Blockstudio 7.4

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 清单,该文件夹就会成为一个集合:

Text
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
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:

Markdown
---
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
<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
<?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 文档

内容同步

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

命令行
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 文档

更可靠的同步

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 仍然优先。未知的前缀标签会保持原样,现有的区块标签允许和拒绝过滤器仍适用于通过前缀解析的区块。

阅读区块标签文档

运行时和编辑器修复

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 让项目的更多内容,包括页面结构和精选内容,都能保存在这些文件中并随文件一起迁移。