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 清单,该文件夹就会成为一个集合:
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
{
"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:
---
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 会使用该布局包装同步后的页面内容。
<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>
新的辅助函数会将集合作为结构化数据公开:
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
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。
内容同步
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 重写。
这为团队提供了一种简洁的方式,可将团队成员、案例研究、地点、文档条目或其他结构化记录等精选内容纳入版本控制,而无需将整个生产数据库变成迁移对象。此功能适用于仍可作为文件审核的内容集:几十或几百条记录;在某些项目中,如果内容结构清晰且变更少,也可以达到数千条。它不能替代数据库备份,也不适用于电商或订单同步、分析数据、日志、表单提交或其他高容量数据。
更可靠的同步
Blockstudio 现在会检测页面源、集合清单、加载器文件、布局文件、元数据和相关路径中的变更。只要其中任一项发生变化,已同步的 WordPress 页面就会更新。
页面处理流程也能应对各种细节,让基于文件的文档在真实项目中更实用:
- Markdown 页面源会同步为原生区块内容,包括区块属性
- 前端辅助函数和布局可以使用 Frontmatter 元数据
- 集合页面在多次同步之间保持稳定身份
- 嵌套的非集合页面会链接到其父页面
- 非集合嵌套页面可以继承最近祖先页面的
layout.php - 移除集合源后,会清理其生成的 WordPress 页面
- 将集合从
page更改为自定义文章类型时,会迁移现有同步文章,而不是创建重复项 - 页面顺序会通过
menu_order保存
区块标签前缀
区块标签现在支持可配置的命名空间前缀。项目可以注册一个简短前缀,让 Blockstudio 在一个或多个命名空间中解析区块:
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 让项目的更多内容,包括页面结构和精选内容,都能保存在这些文件中并随文件一起迁移。