页面
页面是基于文件的模板,会作为文章同步到 WordPress 数据库。
同步操作需要显式执行:在准备应用源文件更改时,运行 wp bs pages sync 或调用 Pages API。加载前端或 WordPress 管理后台时,不会完整发现页面,也不会修改页面文章。
页面可以定义为单个 page.json 文件夹、独立的 Markdown,也可以定义为带有 pages.json 清单的集合。集合适用于文档、知识库、着陆页库,或任何需要从文件生成的嵌套页面集合。
page.json
对于通过 JSON 定义的页面,请添加 page.json 配置文件:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
属性
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
name |
string |
必填 | 页面的唯一标识符 |
title |
string |
根据名称自动生成 | 页面标题 |
slug |
string |
与名称相同 | 页面的 URL slug |
path |
string |
"." |
集合内的逻辑路径 |
order |
integer |
0 |
同步文章的菜单顺序 |
postType |
string |
"page" |
WordPress 文章类型 |
postStatus |
string |
"draft" |
新文章的状态(publish、draft、pending、private) |
postId |
integer |
– | 将页面固定到指定的 WordPress 文章 ID |
blockEditingMode |
string |
– | 区块编辑模式:"default"、"contentOnly" 或 "disabled" |
templateLock |
string|false |
"all" |
锁定模式:"all"、"insert"、"contentOnly" 或 false |
templateFor |
string|null |
null |
设为某种文章类型的默认模板 |
sync |
boolean |
true |
指定是否允许常规显式协调操作创建或更新文章 |
render |
string|object|false |
– | 使用已注册的页面渲染器渲染页面(参见 组件页面) |
在 page.json、前置元数据和加载器条目中,已识别的键包括 blockEditingMode、collection、content、contentType、defaults、file、html、markdown、meta、name、order、path、postId、postStatus、postType、postTypeArgs、render、slug、template、templateFor、templateLock 和 title。上面未列出的任何键都会存储在页面的 meta 数组中。
内容来源
页面定义决定应存在什么 WordPress 文章。内容来源则决定写入该文章的区块标记。
页面文件夹中包含 page.json 时,Blockstudio 会按以下顺序查找同级源文件:
| 文件 | 用途 |
|---|---|
index.php |
类似 HTML 的区块标记,按原样读取(不执行 PHP 代码) |
index.blade.php |
Blade 模板内容 |
index.twig |
Twig 模板内容 |
index.md |
Markdown 内容 |
page.json 也可以直接提供内嵌的 markdown 或 html,无需使用同级文件:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
集合还支持另外两种来源模式:
- 从集合目录树直接发现的 Markdown 文件。
- 从
loader.php返回的加载器条目。
加载器条目可以使用 markdown、html 或 content 搭配 contentType。也可以指向本地的 file 或 template。除非显式设置 contentType,否则文件和模板来源会根据扩展名推断类型。
支持的 contentType 值包括 php、blade、twig、markdown 和 html。Markdown 会先转换为 HTML,再解析为原生 WordPress 区块。PHP、Blade、Twig 和 HTML 来源会通过常规的 Blockstudio 页面解析器处理。
核心区块上的类
映射到核心区块的 HTML 元素上的 class 会成为其 className。
显式的核心区块标签可以直接使用 className。这两种形式都会保留区块已保存包装元素上的类,以及 WordPress 生成的类:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
如果两个属性都存在,className 优先。此转换仅适用于核心区块:自定义区块映射会保留其 class 字段不变。按钮样式类(例如 is-style-outline)属于按钮包装元素,而非其链接。
运行 wp bs pages sync,将解析器更正应用于先前已同步的页面。无需编辑源文件,下次显式同步时即可识别解析器升级。锁定的页面和带有 sync: false 的页面仍受常规保护;前端请求绝不会执行此同步。
序列化的 WordPress 区块
页面和样式来源也可以包含从 WordPress 代码编辑器复制的序列化区块:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
当源内容包含 <!-- wp:... --> 块分隔符时,Blockstudio 会对整个源内容使用 WordPress 的原生区块解析器。属性、嵌套区块、Query Loop 等动态区块以及 Blockstudio 区块都会保留其序列化结构。区块注释之外的 HTML 仍是原生自由格式 HTML;不会映射为额外区块。不要将 Blockstudio 的 HTML 区块标签与此格式混用,并期待它们被转换。普通的 HTML 注释不会启用序列化区块模式。
Markdown 页面
当你希望将正文放在文件中,但在同步后仍可编辑为 WordPress 区块内容时,请使用 Markdown。同步过程中,Markdown 源会转换为区块标记。同步后的文章存储的是区块,而不是原始 Markdown 正文。
Markdown 有三种用法:
| 来源 | 是否需要 Frontmatter? | 说明 |
|---|---|---|
独立的 pages/example/index.md |
是 | Frontmatter 提供页面标识。 |
page.json 加 index.md |
否 | page.json 定义页面,Markdown 提供内容。 |
| 集合中的 Markdown | 否 | 集合会根据文件位置推断 name 和 path。 |
没有 frontmatter 的独立 index.md 会被跳过,因为 Blockstudio 没有可供同步的页面标识。集合中的 Markdown 无需 frontmatter,因为集合清单和文件路径会提供该标识。
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
你也可以将 page.json 与 index.md 配合使用。此时,page.json 定义页面,index.md 提供内容。index.md 中的 frontmatter 会覆盖匹配的 page.json 值。
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
对于集合 Markdown,除非 frontmatter 覆盖,否则文件路径会成为逻辑页面路径:
| 文件 | 默认路径 |
|---|---|
pages/docs/index.md |
. |
pages/docs/getting-started.md |
getting-started |
pages/docs/guide/install/index.md |
guide/install |
pages/docs/guide/install.md |
guide/install |
未知的 frontmatter 键会保留在页面的 meta 数组中。这样你就可以附加 section 或 description 等数据,并从 PHP API 中读取。
Markdown 会解析为 GitHub 风格的 Markdown。允许原始 HTML,不安全的链接会被移除,没有显式 ID 的标题会获得稳定的 ID。嵌套的 YAML frontmatter 需要使用捆绑的 YAML 解析器。
原始 Markdown
Markdown 文件来源可以提供其原始源 Markdown,供外部工具和文档使用者使用。内嵌的 Markdown 没有源文件,因此它会同步为区块,但不会生成原始 .md 响应。
请求页面时添加 .md 后缀,例如 https://example.com/docs/reference.md。或者向常规页面 URL 发送 Accept: text/markdown 标头:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
响应中会移除 Frontmatter。成功的原始 Markdown 响应会向 HTML 页面返回 Content-Type: text/markdown、X-Robots-Tag: noindex 和规范的 Link 标头。缺失的 .md 路由会返回真正的 404。
此协商机制适用于静态预渲染:Accept 标头包含 text/markdown 的请求不会从预渲染存储或提前服务的 drop-in 中获得响应,因此会到达 WordPress 和 Markdown 处理器。预渲染的 HTML 响应、同时也协商 Markdown 的页面的 HTML,以及通过 Accept 响应的 Markdown,都会发送 Vary: Accept,因此遵循 Vary 的缓存会将两者区分开来。若 CDN 只根据 URL 设置缓存键,则需要自行设置规则,让此类请求绕过缓存。Pages::negotiates_markdown( $post_id ) 会报告页面是否响应 Markdown 请求。
集合 Markdown 对原始 Markdown 保持相同的 URL 结构:
| 页面 URL | 原始 Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
使用 blockstudio/pages/serve_markdown 筛选器禁用原始 Markdown 响应:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
如果 .md URL 未解析到由 Markdown 支持的页面,只有当路径位于页面集合内时才会返回 404。在所有集合之外,Blockstudio 不会拦截请求,由 WordPress 和其他插件处理。
组件页面
组件页面由页面渲染器渲染,而不是存储为区块。Blockstudio 不附带渲染器。主题或插件会为其处理的条目文件注册渲染器,例如用于 page.tsx 的 React 渲染器;Blockstudio 会将页面、WordPress 文章和渲染后的插槽内容传递给它。
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render 是显式指定的。如果目录中有 index.php 和 page.tsx,但没有 render,它仍是普通页面,因此添加渲染器不会导致现有页面被渲染两次。形式如下:
| 值 | 含义 |
|---|---|
"page.tsx" |
仅有条目,没有数据加载器 |
{ "entry": "page.tsx", "data": "data.php" } |
条目和数据加载器 |
{ "entry": "page.tsx", "renderer": "react" } |
带有显式渲染器 ID 的条目 |
false |
不使用渲染器,即使集合默认值指定了渲染器也是如此 |
路径相对于页面目录解析;对于加载器条目,则相对于集合根目录解析。除非 blockstudio/pages/allow_external_loader_path 允许,否则路径必须位于发现源内部。若没有 renderer,则使用声明了该条目扩展名的渲染器。render 若指向缺失的条目或数据文件、未知渲染器,或没有渲染器声明的扩展名,就会导致发现错误,并使协调操作在清理任何内容之前失败。
同步会存储什么
同步会存储一个 blockstudio/page 区块。如果页面目录中还有 index.* 源文件,就会像解析任何页面源文件一样解析该源文件,并将其内容作为区块的内部区块,也就是插槽:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
将由 WordPress 管理的内容(例如短代码)保留在插槽中。若源文件只包含一个短代码(例如 [download_checkout]),则会将其存储为 core/shortcode 区块,因此其输出周围不会包裹段落。它会保留在 post_content 中,因此 has_shortcode() 检查可以看到它;带键的插槽区块会像嵌套的带键区块一样与编辑器的更改合并;do_shortcode 会在通常的 the_content 优先级下展开短代码一次,也就是渲染器为其添加外层结构之后。
渲染定义会以可移植的 theme: 路径与文章一同存储。页面指纹涵盖该定义,而不涵盖条目或数据加载器的字节内容:编辑 page.tsx 或 data.php 不会更改文章;访客会通过渲染以及 静态预渲染图 获取这些更改。该图会记录条目、数据加载器,以及渲染器报告的每个文件。
注册渲染器
在 blockstudio/pages/renderers 操作上注册渲染器。它会在每个请求中触发一次,并且发生在首次发现或渲染之前,因此 wp bs pages sync 请求和前端请求会看到相同的注册表。
add_action(
'blockstudio/pages/renderers',
static function (): void {
Blockstudio\Page_Renderers::register(
'react',
array(
'extensions' => array( 'tsx' ),
'layouts' => array( 'layout.tsx' ),
'render' => 'my_theme_render_page',
)
);
}
);
渲染器 ID 使用小写字母。一个扩展名或布局名称只能属于一个渲染器,而 layout.php 保留为 Blockstudio 自己的布局。可调用对象接收一个请求:
| 键 | 值 |
|---|---|
kind |
page;对于 渲染器布局,则为 layout |
renderer |
渲染器 ID |
entry |
绝对条目路径 |
data |
绝对数据加载器路径,或 null |
page |
规范页面数据,包括 meta |
post_id |
WordPress 文章 ID |
slot |
已渲染的插槽内容;对于布局,则为页面内容 |
context |
frontend、rest、feed 或 cli |
它会返回 HTML、渲染时读取的文件,以及可选资源:
function my_theme_render_page( array $request ): array {
return array(
'html' => '<main>...</main>',
'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
'assets' => array( array( 'path' => '/abs/path/to/page.js' ) ),
);
}
context 来自请求类型,而非访客,因此渲染器不会因为读取它而破坏已登录用户和匿名用户之间的字节一致性。如果渲染器失败,就会抛出异常:页面不会渲染出空白正文。在 REST 编辑器预览中,区块会改为以通知形式显示错误。成功渲染后,blockstudio/pages/rendered 操作会接收页面、HTML 及其依赖项。
assets 列出页面所需的脚本和样式文件。这些文件会经过区块资源的处理流程(*.inline.* 约定、ES 模块、压缩和 ?ver),页面也会通过输出区块资源的同一缓冲区将它们输出一次,因此预渲染的页面也会包含这些文件。资源可以设置 version,以替换其 ?ver 值。渲染器外部的代码也可以通过 Blockstudio\Assets::register_owner() 使用同一通道;它会返回要输出的标记注释。
编辑器
在编辑器中,blockstudio/page 会显示页面的服务器端渲染预览,其中插槽作为内部区块,并遵循页面的 templateLock。此区块不能插入、复制,也不能嵌套在其他区块中。
页面集合
集合是带有 pages.json 清单的文件夹。它会将多个页面来源归入一个集合别名,应用默认值,支持嵌套路径,并可自动注册专用文章类型。
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| 属性 | 类型 | 说明 |
|---|---|---|
collection / slug / name |
string |
集合别名。collection 是最清晰的形式,并会成为公开的 URL 基础路径。 |
title |
string |
面向用户的集合标题。 |
postType |
string |
生成页面所用的文章类型。默认为 page。如果该类型不存在,Blockstudio 会注册它。 |
postTypeArgs |
object |
在 Blockstudio 注册集合文章类型时,传递给 register_post_type() 的参数。 |
defaults |
object |
应用于集合中每个页面的默认页面属性。只有当页面目录中存在对应条目时,默认的 render 才会应用于该页面。 |
scope |
string |
collection(默认)或 site。请参阅站点集合。 |
meta |
object |
自定义集合元数据。清单中未知的键也会存储在 meta 中。 |
集合页面路径是逻辑路径。带有 path: "guide/install" 的页面会作为 guide 的子页面同步;如果存在父页面,guide 会作为集合根页面的子页面同步。
如果分层集合中有嵌套页面,但中间层的父页面源不存在,Blockstudio 会为该路径生成空容器页面,从而保持 WordPress 层级完整。非分层文章类型(不支持 page-attributes 父级的类型)不会生成空容器。它们会根据存储的集合路径进行路由,因此即使 guide/install 和 setup/install 最终都以 install 结尾,也可以同时存在。
集合文章类型与 URL
在集合清单中设置 postType,即可将集合中的每个页面同步到该文章类型。无需在 defaults 中重复相同的值。各个页面仍可在 frontmatter 或 page.json 中覆盖 postType。
如果文章类型不存在,Blockstudio 会注册它,设置 show_in_rest: true、类似页面的编辑器配置,并将集合别名设为公开的 URL 基础路径。postTypeArgs 可以覆盖注册参数。注册的集合文章类型或重写参数发生变化时,集合文章类型的重写规则会自动刷新,因此无需重新保存 WordPress 固定链接。
集合 URL 使用集合别名以及每个页面的逻辑 path:
| 源路径 | 公共 URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
此 URL 模型同时适用于分层和非分层的集合文章类型。Blockstudio 还会将重复两次的 URL(例如 /docs/docs/ 或 /docs/docs/getting-started/)重定向到规范 URL。
集合页面会在相同 URL 下公开原始 Markdown(参见 原始 Markdown)。
如果将集合从 postType: "page" 改为自定义文章类型,Blockstudio 会在已同步的集合文章所存页面标识匹配时原地迁移这些文章。这样可以保留文章 ID、元数据和现有内容,同时避免产生重复的旧类型文章。根据 blockstudio/pages/orphan_action 筛选器清理所有文章状态中的过期集合文章。
站点集合
包含 "scope": "site" 的清单会将其下的所有页面归为一组,但不会将它们转换为集合页面。请在站点页面树的根目录中使用它,以应用共享默认值,并通过 blockstudio_page_tree( 'my-site' ) 列出站点页面。
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
站点集合中的页面保留其在没有清单时完全相同的身份,因此将集合加入现有页面树不会更新任何文章记录,也不会创建或移除任何内容:
- 键保持全局:
Pages::get_page( 'home' )与存储的页面键继续保持对应。 - URL 保持为 WordPress 页面 URL。不应用集合重写规则、固定链接筛选器或双重 URL 重定向,也不会生成空容器页面。
- 逻辑路径、别名、父级和来源身份与独立页面相同,布局按最近的祖先解析。
- 嵌套的
pages.json清单保留各自的集合,其子树不会纳入站点集合。 - 默认值按页面应用:仅当页面目录中存在对应条目时,默认的
render才会应用于该页面,因此短代码和 Markdown 页面会保留其来源。
集合加载器
集合可以包含受信任的本地 loader.php。当集合页面来自其他本地来源时可以使用它,例如外部文档文件夹、软件包或生成的清单。
加载器会在显式页面发现和同步期间运行。它应当是确定性的,并且仅使用本地资源。避免从 loader.php 获取远程内容,因为这会使部署同步依赖该服务。
<?php
return array(
'meta' => array(
'source' => 'loader',
),
'paths' => array(
__DIR__ . '/external-docs',
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
'pages' => array(
array(
'name' => 'docs-api',
'title' => 'API',
'path' => 'api',
'content' => "# API\n\nGenerated markdown content.",
'contentType' => 'markdown',
),
array(
'name' => 'docs-template',
'title' => 'Template',
'path' => 'template',
'file' => __DIR__ . '/template.md',
),
),
);
加载器可以返回一个包含 pages、meta 和 paths 键的数组:
| 键 | 说明 |
|---|---|
pages |
页面数组列表。每个页面支持与 page.json 和 Markdown frontmatter 相同的已识别键。 |
meta |
合并到每个加载器生成页面的 meta 数组中的元数据。 |
paths |
作为此集合一部分进行发现的其他本地目录。条目可以是字符串或路径对象。 |
render |
为从 paths 发现的每个 Markdown 页面定义一个渲染定义。 |
作为简写,加载器可以直接返回页面数组列表。
加载器页面条目可以通过以下方式提供内容:
| 形式 | 说明 |
|---|---|
markdown |
内联 Markdown 内容。 |
html |
内联 HTML 内容。 |
content + contentType |
通用内联内容。contentType 必须解析为 markdown 或 html。 |
file |
本地文件来源。除非设置了 contentType,否则会根据扩展名推断类型。 |
template |
file 的别名。 |
加载器文件引用可以指向 PHP、Blade、Twig、Markdown 或 HTML 来源。相对路径从集合根目录解析。只有在 blockstudio/pages/allow_external_loader_path 筛选器允许时,才能使用绝对路径和集合根目录之外的路径。
加载器页面默认使用 generated: true。当生成的加载器页面从加载器输出中消失时,Blockstudio 会在下次同步时将已同步文章视为孤立文章,并根据 blockstudio/pages/orphan_action 筛选器进行清理。
会像普通集合文件夹一样发现 paths 中列出的目录。它们可以包含 Markdown 文件或 page.json 文件夹。如果这些路径位于集合根目录之外,则适用相同的外部路径筛选器。
如果外部目录应保留自己的逻辑路径,请使用字符串条目。如果目录应挂载到集合路径前缀下,请使用对象条目:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
采用此配置后,集合中的 cli-docs/index.md 会变为 path: "cli",cli-docs/getting-started.md 会变为 path: "cli/getting-started"。前缀还能避免生成的页面名称冲突,因此多个已挂载目录都可以包含 index.md 或 getting-started.md。如果希望保留来自 page.json 或 Markdown frontmatter 的显式 name 值,请在路径对象上将 preserveNames 设为 true。
路径对象属性:
| 属性 | 类型 | 说明 |
|---|---|---|
path |
string |
要发现的本地目录。相对路径从集合根目录解析。 |
prefix |
string |
集合内可选的逻辑路径前缀。 |
preserveNames |
boolean |
保留显式页面名称,而不是根据带前缀的路径生成名称。设置 prefix 时,默认为 false。 |
meta |
object |
合并到从此路径发现的每个页面中的元数据。页面级元数据在重复键时优先。 |
render |
string|object |
为此路径中的 Markdown 页面定义渲染方式,覆盖加载器的 render。 |
通过组件渲染 Markdown
使用 render 后,加载器发现的 Markdown 页面会通过页面渲染器渲染,而不是存储为区块:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
它们仍是 Markdown 页面:内容类型、内容路径、.md 响应和 frontmatter 都保持不变。同步时会存储一个 blockstudio/page 区块,其内部 HTML 是转换后的 Markdown;如果集合会清理其内容,则此内容也会经过清理。它取代了解析后的区块,因此 post_content 会保留文档文本。渲染器会将该 HTML 作为插槽接收,并可从 page.content_path 读取来源。相对路径从集合根目录解析;外部路径筛选器的应用方式与这些路径相同。frontmatter 设置了自身 render 或 render: false 的页面会被排除在外。
布局
layout.php 文件会包装基于文件的页面在前端的渲染。它不会替换存储在 WordPress 中已同步的 post_content,也不会包装编辑器画布。布局仅在前端单页请求时运行。
对于集合,将 layout.php 放在 pages.json 旁边,即可包装该集合中的每个前端页面:
<?php $current = blockstudio_current_page(); ?>
<main class="docs-layout">
<aside>
<?php foreach (blockstudio_page_tree('docs') as $item) : ?>
<?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
<a
href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
<?php echo $is_current ? 'aria-current="page"' : ''; ?>
>
<?php echo esc_html($item['title']); ?>
</a>
<?php endforeach; ?>
</aside>
<article>
<?php echo blockstudio_page_content(); ?>
</article>
</main>
blockstudio_page_content() 会输出页面正文,WordPress 通常会通过 the_content 渲染该正文。如果布局未输出 blockstudio_page_content(),页面内容将被有意隐藏。
布局可以使用页面辅助函数:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
非集合的嵌套页面也可以继承 pages 树中最近祖先的 layout.php。对于集合页面,集合根布局会存储在每篇已同步文章上,并作为页面指纹的一部分进行监视,因此布局变更会在下次同步时生效。
渲染器布局
布局也可以是渲染器入口,例如 layout.tsx,供注册 layouts: ["layout.tsx"] 的渲染器使用。它会在与 layout.php 相同的位置查找,其旁边可选的 layout.data.php 则是它的数据加载器。渲染时,渲染器会接收 kind: "layout" 和作为 slot 的已渲染页面内容,其优先级与 layout.php 相同,均为 the_content。目录可以包含 layout.php 或一个渲染器布局,但不能同时包含两者;同时包含属于发现错误。布局失败时会触发 blockstudio/pages/layout_error,并保持页面内容不被包装,这与 layout.php 的处理方式相同。
区块编辑模式
blockEditingMode 属性控制编辑器中区块的编辑方式。在 page.json 中设置页面级默认值,并在模板中按元素覆盖:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| 值 | 说明 |
|---|---|
"default" |
完全编辑。可以选择、移动和编辑区块 |
"contentOnly" |
仅编辑文本。区块文本可编辑,但设置和结构已锁定 |
"disabled" |
不可编辑。区块完全不可交互 |
可以在任意元素(<h1>、<p>、<div> 等)或 <block> 元素上通过 HTML 属性设置单个元素覆盖。被覆盖元素的祖先容器区块会自动设为 contentOnly,以便其子元素仍可访问。此级联会从被覆盖元素向上遍历到页面根节点,因此只需在要设为可编辑的元素上设置 blockEditingMode。
模板锁定
templateLock 属性控制用户在编辑器中编辑页面的方式:
| 值 | 添加/移除 | 移动 | 编辑内容 |
|---|---|---|---|
"all" |
否 | 否 | 否 |
"insert" |
否 | 是 | 是 |
"contentOnly" |
否 | 否 | 是 |
false |
是 | 是 | 是 |
设置 templateLock 后,Blockstudio 会在编辑器 UI 中禁用解锁区块的功能。
虚拟路由
有些文档背后没有文章:例如根据数据生成的组件参考、目录或账户区域。可以将其注册为虚拟路由,而不是自行挂接 template_redirect:
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );
路径相对于站点主页。使用 prefix 时,该路由还会处理其下的所有路径;match 会接收剩余路径(路由本身对应空字符串),并返回渲染回调接收的值,或返回 null,以便将 URL 留给 WordPress,后者随后照常响应 404。渲染回调会输出文档,或将其作为字符串返回;title 是一个字符串,或一个接收匹配值的闭包。
对于匹配的请求,Blockstudio 会阻止 WordPress 将其标记为 404,并阻止 redirect_canonical 重定向它;清除主查询报告的单页状态;发送状态码(默认值为 status、200);并以 template_redirect 优先级 Virtual_Routes::PRIORITY 渲染。这发生在 Blockstudio 于 Assets::BUFFER_PRIORITY 打开输出缓冲区后,因此最终文档会像任何页面一样获得区块资源、打包的 UI 资源和编译后的 Tailwind,并且早于优先级为 10 的 redirect_canonical。自行渲染整个文档的处理程序还必须在 Assets::BUFFER_PRIORITY 之后运行,否则会跳过该处理。urls 中的路径(默认是路由路径本身,前提是它不是前缀路由)会添加到 静态预渲染 构建中,而 Virtual_Routes::urls() 会将其作为绝对 URL 返回,以供站点地图使用。Virtual_Routes::match( $path ) 会像请求一样解析路径。
同步行为
页面文章只会通过显式同步操作发生变更:
wp bs pages sync
该命令会发现完整的源清单,创建或更新有变更的文章,清除已确认的孤立文章,刷新集合路由和已编译的 templateFor 配置,并报告变更内容。添加 --authoritative 可替换受管理的内容,而非保留带键的编辑器内容;添加 --full 可将此轮报告为完整协调,无论已存储的源标识如何:
wp bs pages sync --authoritative --full
普通前端、管理后台、AJAX、REST、cron 和通用 WP-CLI 引导请求不会执行完整页面发现、查询受管理的协调清单,也不会写入页面文章。它们使用已同步的 WordPress 文章,以及上次显式操作所持久化的精简集合和文章类型模板配置。全新安装或升级时,可能会扫描一次集合清单以恢复路由元数据;此只读引导过程绝不会同步内容。经身份验证且选择启用的 Canvas 刷新端点是一项显式编辑操作 API:工作区打开时,Canvas 会调用一次该端点,使新添加或已变更的来源出现在初始清单中。实时模式发现页面来源变更时,也会调用同一边界。
Blockstudio\Pages::init() 现在只会注册请求时钩子。此前向该方法传递 force 参数的集成必须改为调用 Blockstudio\Pages::reconcile(),或改为运行 wp bs pages sync。
为防止手动编辑后页面被覆盖,请在 page.json 中设置 "sync": false。
可移植的源文件位置
同步的主题文件以相对于主题的位置存储,而不是绝对安装路径。子主题文件和父主题文件会保留不同的身份,即使它们的相对文件名相同。对于当前请求,页面辅助函数仍会返回已解析的绝对 template_path、content_path、layout_path 和 directory 值。
这样一来,CLI同步和 Web 请求可以使用不同的文件系统根目录,例如在受限主机环境中,同时不会影响Markdown响应、布局、编辑器Tailwind扫描或预渲染源跟踪。主题目录名称未更改时,读取过程中会重新映射现有的绝对主题路径。读取这些路径无需同步、数据库迁移或在请求时写入元数据;下一次显式同步会存储可移植的位置。
如果主题目录是符号链接(例如指向开发检出目录的链接),无论源文件是通过符号链接还是其目标读取,都会存储相同的theme:位置,并将其解析到已配置的主题目录。
活动子主题和父主题之外的文件仍受支持,并保留其已配置的绝对路径,但受PHP的open_basedir限制。这些路径不会自动迁移:移动外部源文件后,请更新其已配置的路径并运行显式同步。
文章字段的所有权
postStatus设置初始状态。后续同步会保留现有的草稿、待处理、私有、已发布和已计划状态,包括使用--authoritative时。文件中写有postStatus: "publish",并不会因此重新发布草稿。现有的孤立项恢复行为保持不变:如果源文件仍存在,显式同步会恢复已移至回收站的托管文章。锁定页面或禁用同步可防止此类恢复。
文件仍负责定义标题、别名、文章类型、父级和已配置的菜单顺序。在WordPress中编辑这些字段不会更改源定义。下一次显式同步会重新应用文件中的值,并在pages.<name>.overwritten中列出受影响的字段,同时在CLI表格输出中发出警告。WordPress的原生权限仍然适用;例如,当同步用户无法发布文章时,待处理文章的别名会为空。
如果集成明确需要采用不同的状态策略,请使用blockstudio/pages/update_post_data。带键的区块会保留由编辑器管理的区块内容;这些键不会改变文章标题或别名的所有权。
对于集合页面,指纹涵盖清单、加载器、页面来源、布局文件、元数据和相关来源路径。下次显式同步时会应用这些输入的变更。
移除集合来源时,Blockstudio 会移除生成的页面,避免来源文件删除后旧集合页面仍然存在。默认情况下,孤立的集合页面会移至回收站。使用 blockstudio/pages/orphan_action 可返回 trash、delete 或 keep。
在前端请求中,Blockstudio 会从已同步的已发布文章中填充页面注册表。草稿和私密页面可在管理后台和同步上下文中使用,但前端辅助函数只会填充已发布页面。
部署协调
Blockstudio\Pages::reconcile() 是 PHP 部署入口点。它会发现完整的预期清单,比较来源和同步引擎指纹,并返回机器可读的报告:
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
'renames' => [
[
'from' => 'pages/old/index.php',
'to' => 'pages/new/index.php',
],
],
]);
报告包含discovered、created、updated、unchanged、locked、preserved、removed、removedPages、failed、fullReconciliation、逐页结果、发现错误,以及确定性的sourceIdentity。
已锁定页面带有status: "locked",并与未更改页面分开计数。removedPages会列出每个已移除页面的name、key、postId和实际action(trash或delete);保留的文章或已移至回收站的文章不会计为新移除项。CLI表格输出还会列出已创建、已更新、已锁定、已移除及内容已保留的页面及其文章 ID。
解析并按键合并后,如果最终文章完全相同,就不会调用wp_update_post()、更改post_modified、创建修订版本或触发文章更新钩子。结果为unchanged。如果源内容与由编辑器管理的带键内容不同,preserved: true会标明这一处理决定,顶层的preserved计数也会将其计入。系统仍会记录新的源指纹和托管元数据,因此下一次内容未变的同步将不执行任何操作。preserved是附加标志,并非唯一状态:页面可以保留带键内容,同时更新由文件管理的标题或添加其他区块。
authoritative: true 可能会清除页面同步锁,并使用文件定义替换内容,而不是保留带键的编辑器内容。普通显式同步时请将其保留为 false。plan_valid: false、full: true、broad: true、缺少先前的来源标识或同步引擎指纹变更,都会将此轮标记为完整协调(报告中的 fullReconciliation)。无论如何,每轮都会比较完整清单。Git 重命名记录仅作为标识提示,绝不会取代完整清单比较。
指纹相同且运行时路径未变时,不会写入文章或文章元数据,也不会触发更新钩子。当未变更的来源移入新的发布目录时,协调操作只会刷新其持久化的模板、内容、布局和目录路径;不会更新 post_content 或文章修改时间戳。只有在完整协调操作结束且没有发现错误或页面写入错误后,才会清理缺失的受管理页面。
直接进行 API 协调不会将部署标记为成功。激活并验证匹配的静态产物和路由后,请显式保存返回的标识:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync 会在操作成功后存储返回的标识。普通的 WP-CLI 引导过程只会注册持久化的集合文章类型和重写规则,不会发现或同步页面。
固定文章 ID
默认情况下,WordPress 会自动分配文章 ID。如果删除页面后重新创建,ID 会发生变化,从而破坏菜单或硬编码链接等外部引用。
使用 postId 将页面固定到特定 ID:
{
"name": "about",
"title": "About Us",
"postId": 42
}
创建页面时,Blockstudio 会通过 import_id 将 ID 传给 WordPress。如果该 ID 可用,WordPress 会原样使用。如果该 ID 已被无关的文章占用,WordPress 会静默地自动分配一个新 ID。
查找现有页面时,Blockstudio 会先检查固定 ID,然后再检查元数据或别名。这意味着删除页面并重新同步后,它会重新获得相同的 ID。
带键区块合并
默认情况下,模板文件发生变更时,Blockstudio 会用新模板替换整篇文章的内容。这意味着在 WordPress 编辑器中所做的任何修改都会丢失。
为区块添加 key 属性,即可在模板同步期间保留用户修改。模板包含带键区块时,Blockstudio 会将模板变更与现有文章内容合并,而不是直接替换。
添加键
在任何 HTML 元素或 <block> 元素上使用 key 属性:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
键在整个模板中必须全局唯一。键会保护整个区块及其全部内容。带键的父区块中的各个子区块无需单独设置键。在模板更新之间,带键区块可以移动到任意位置或嵌套层级,其用户内容仍会得到保留。
键对 Blockstudio 自定义区块的作用方式相同。key 是结构性页面同步元数据;自定义字段值仍是普通的 Blockstudio 属性。编辑器更改这些字段后,后续模板同步会保留编辑器中的值,同时应用彼此独立的模板变更。较旧版本创建且键位于自定义字段数据中的页面,会在下次同步时自动迁移。
合并方式
模板文件变更且页面重新同步时:
| 区块 | 行为 |
|---|---|
| 带键区块 | 保留用户内容和 Blockstudio 字段值。应用模板拥有的属性和结构。 |
| 不带键区块 | 完全替换为模板版本(与不使用键时相同) |
示例
带键区块中的用户修改会得到保留:
- 模板定义
<p key="intro">Default intro.</p> - 用户在编辑器中将段落改为“自定义简介文本。”
- 开发者更新模板,添加新区块并更改布局
- 同步时:段落保留“自定义简介文本。”,同时应用新布局
模板中的属性仍会生效:
- 模板包含一个封面区块,其中有
key="hero"和url属性 - 开发者将封面的
url属性更改为新的背景图片 - 同步时:应用新的背景图片,同时保留用户在封面内所做的内容修改
边缘情况
| 情况 | 行为 |
|---|---|
| 模板中添加了新的带键区块 | 使用模板默认内容显示 |
| 从模板中移除了带键区块 | 从文章中删除 |
| 区块类型变更(键相同) | 完全以模板为准,不合并内容 |
| 键重复 | 第二次出现的区块视为不带键 |
| 模板中没有键 | 完全替换(与不使用键时的行为相同) |
| 强制同步 | 完全替换,忽略键 |
| 已锁定的文章 | 完全不同步 |
与编辑控制配合使用
键、templateLock 和 blockEditingMode 配合使用,可精细控制客户可以和不可以执行的操作。以下是常见的工作流程模式。
完全锁定的页面
开发者控制所有内容。页面是客户完全无法操作的静态布局。适用于法律页面、服务条款,或任何只能通过代码更改的页面。
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
无需设置键。模板是唯一事实来源。每次同步都会完全覆盖页面。
锁定布局并允许编辑内容
这是最常见的模式。锁定页面结构,避免客户添加、移除或重新排列区块,同时允许他们在特定位置编辑文本。使用键可确保他们的修改在模板更新后仍会保留。
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
客户端可以编辑主视觉标题、描述和功能介绍,仅限这些内容。按钮文字、URL和封面背景图由开发者控制。开发者更新模板(e.g.,添加第二个按钮)时,带键名的区块会保留客户端的文本。
不丢失内容的模板演进
适用于随时间不断扩展的页面。开发者向模板添加新区块,每次同步都会添加新内容,而不影响客户端已自定义的内容。
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
同步时会显示新的客户评价区块和按钮。标题、介绍和服务内容中的客户端修改会保持不变。
一次性搭建
创建一个具有初始结构的页面,然后将其完全交给客户。将 sync 设为 false,这样常规同步就不会创建或更新该页面;然后使用 Blockstudio\Pages::force_sync('blog') 创建一次。之后,页面就完全由客户负责。
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync 会跳过此页面,因此 force_sync() 会创建一次。之后,客户可以自由添加、移除和重新排列区块。模板变更会被忽略。
区块绑定
键控合并的另一种方式是使用 WordPress core 的 区块绑定API 将区块连接到文章元数据。这不是 Blockstudio 功能,而是原生的 WordPress API。Blockstudio 只会将 metadata 属性传递给生成的区块标记。内容存储在文章元数据中,而不是区块标记中,因此模板同步可以自由覆盖标记,因为编辑器读取的是元数据,而不是 innerHTML。
在任何 HTML 元素或 <block> 元素上设置 metadata 属性:
<h1
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
Default Title
</h1>
<p
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
Default description text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
元数据键必须在注册时启用 show_in_rest:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
键与绑定的比较
| 方面 | 键 | 绑定 |
|---|---|---|
| 内容存储位置 | 区块标记(post_content) |
文章元数据(wp_postmeta) |
| 模板同步后是否保留 | 是(按键合并) | 是(数据存储在元数据中) |
能否通过 WP_Query 查询 |
否 | 是(meta_query) |
| 是否可用于 REST API | 否 | 是 |
| 是否需要注册 | 否 | 是(register_post_meta) |
| 用户能否移动区块 | 否(模板会重新强制应用结构) | 否(模板会重新强制应用结构) |
这两种方式可以在同一模板中同时使用。对于区块结构很重要的区块组(e.g.,包含多个子项的组),请使用键。对于单独的字段,如果还希望在区块编辑器之外访问数据,请使用绑定。
文章类型模板
使用 templateFor 将页面设为某种文章类型的默认模板:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
该类型的任何新文章都会从定义好的区块结构开始。
自定义路径
默认情况下,Blockstudio 会扫描 get_template_directory() . '/pages'。使用此筛选器添加其他路径:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
负责组合多个根目录文件的运行时集成可以用逻辑发现源替代文件系统扫描。页面清单、布局、加载器和源模板随后会按逻辑路径解析,即使选定文件位于不同根目录中也是如此。
筛选器和操作
页面发现、同步和集合路由提供了以下扩展点:
| 钩子 | 类型 | 说明 |
|---|---|---|
blockstudio/pages/paths |
筛选器 | 添加Blockstudio用于扫描页面源文件的目录。 |
blockstudio/pages/collection_post_type_args |
筛选器 | 调整集合 CPT 的register_post_type()参数。 |
blockstudio/pages/template_candidates |
筛选器 | 调整页面源文件所考虑的模板文件名。 |
blockstudio/pages/serve_markdown |
筛选器 | 启用或禁用原始Markdown响应。 |
blockstudio/pages/orphan_action |
筛选器 | 为孤立项清理返回trash、delete或keep。 |
blockstudio/pages/docs_allowed_html |
筛选器 | 调整生成的Markdown文档内容允许使用的HTML。 |
blockstudio/pages/allow_external_loader_path |
筛选器 | 允许加载器paths位于集合根目录之外。 |
blockstudio/pages/manifest_scan_interval |
筛选器 | 设置旧版 pre-7.6.2清单缓存的最长存留时间;升级时可使用该缓存来填充持久化运行时配置。 |
blockstudio/pages/create_post_data |
筛选器 | 在创建同步页面之前修改文章数据。 |
blockstudio/pages/update_post_data |
筛选器 | 在更新同步页面之前修改文章数据。 |
blockstudio/pages/sync_engine_inputs |
筛选器 | 添加解析器、映射或迁移版本,以便有意触发一次范围更广的协调。 |
blockstudio/pages/post_created |
操作 | 在创建同步页面文章后运行。 |
blockstudio/pages/post_updated |
操作 | 在更新同步页面文章后运行。 |
blockstudio/pages/synced |
操作 | 在页面注册表完成同步后运行。 |
blockstudio/pages/reconciled |
操作 | 在执行显式协调后运行,并附带机器可读报告。 |
blockstudio/pages/renderers |
操作 | 使用Blockstudio\Page_Renderers::register()注册页面渲染器。每个请求触发一次。 |
blockstudio/pages/rendered |
操作 | 组件页面渲染后运行,并附带页面、其HTML及其依赖项。 |
blockstudio/pages/layout_error |
操作 | 布局无法渲染时运行,并附带错误、布局路径和页面。 |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
有关参数语义、报告字段和已验证的源身份边界,请参阅部署协调。
模板和布局可使用全局辅助函数:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Blockstudio\Pages::pages()、Blockstudio\Pages::tree()、Blockstudio\Pages::children()以及全局辅助函数返回的页面数组,包含已同步文章的标识、源路径和模板路径、集合/路径元数据、内容类型、同步策略、文章类型/状态、编辑策略、自定义元数据,以及一个 permalink 键。集合元数据从最近一次成功的显式协调中加载。常规请求会根据持久化配置和已同步文章元数据重建这些运行时数据,而不会读取页面源目录树。Pages 类不提供单独的永久链接方法。
模板锁定、区块编辑模式、键控合并,以及控制客户端可编辑的内容。