来自文件的站点编辑器模板和模板部件
区块主题会在 templates/*.html 和 parts/*.html 中描述布局:这些文件充满了序列化区块注释,例如 <!-- wp:template-part {"slug":"header"} /-->。没人喜欢手动编写这些内容,因此通常会在站点编辑器中构建后再导出。如果两个人同时编辑同一个模板,或者审阅者必须阅读 HTML 注释中经过转义的 JSON 差异,这种方式就不太方便了。
Blockstudio 让你能像编写基于文件的页面一样编写模板:创建一个带有简短 JSON 清单的文件夹,再添加一个使用类似 HTML 标记的源文件,其中可以使用普通元素、<block> 标签以及你自己的 Blockstudio 区块。
Blockstudio 会将源文件编译为原生区块标记,并作为主题文件交给 WordPress。站点编辑器仍与以往完全相同:用户可以自定义模板,重置后则会恢复文件版本。
本指南将构建页眉和页脚部件、首页和单篇模板,以及供编辑者选择用于页面的自定义模板,然后展示 WordPress 如何解析它们。
文件夹结构
模板放在 templates/ 中,模板部件放在 parts/ 中。每个模板或部件都是一个文件夹,包含清单和一个源文件:
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
这些是 WordPress 为区块主题读取的同一组 templates/ 和 parts/ 文件夹。Blockstudio 会先扫描当前主题,再扫描父主题。包含 template.json 或 part.json 的文件夹属于 Blockstudio 源;旁边的普通 .html 文件仍是原生 WordPress 模板。
源文件可以是 index.php、index.blade.php、index.twig 或 index.html,按此顺序检查。Twig 需要 Timber,而 Blade 需要其渲染器包,详见模板引擎。
第 1 步:页眉部件
每个部件都需要一个 part.json。area 用于告知站点编辑器该部件所属的位置:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
源文件使用与 Blockstudio 页面和图案相同的语法。<div> 会变成群组区块,属性会变成区块属性,而 <block> 元素会生成任何已注册区块:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio 会将其编译为以下区块标记:
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
这就是你原本需要手动编写的内容。你自己的区块也一样:<block name="acme/announcement" />、<bs:acme-announcement /> 标签或已配置的标签前缀,都会编译为该区块的注释。
第 2 步:页脚部件
部件可以小到只有一个段落。这里使用 index.html 来说明源文件是标记,而不是程序:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
它会编译为 <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->。
第 3 步:首页和单篇模板
模板使用 template.json。slug 必须是精确的 WordPress 模板层级名称,例如 front-page、single、page、archive、404 或 single-product。Blockstudio 绝不会为其添加前缀。
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
单篇文章模板采用相同结构,但使用文章区块:
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
编译后的单篇模板:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main> 变成了带有 tagName: "main" 的群组区块,模板部件区块则通过 slug 引用第 1 步和第 2 步中的部件。WordPress 渲染模板时,这些引用会解析为基于文件的部件,因此首页输出以包含站点标题和导航的 <header class="wp-block-template-part"> 开头,并以包含页脚段落的 <footer class="wp-block-template-part"> 结尾。
第 4 步:页面自定义模板
slug 不属于层级结构的模板就是自定义模板。使用 postTypes 列出它们适用的文章类型,编辑者就可以在模板选择器中选择这些模板:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) 现在包含 page-landing,模板对象也带有 post_types: ["page"]。
源文件只编译一次
源文件会被读取并编译为区块标记,且只编译一次,而非每次请求都编译。此时没有当前文章,也没有请求上下文。index.php 会被作为标记读取:其中的 PHP 代码不会执行,因此 <?php echo get_bloginfo( 'name' ); ?> 会编译为空。所有依赖请求的内容都应放在运行时渲染的区块中:使用 core/site-title,而不是输出站点名称;使用 core/post-title,而不是 the_title();或者使用你自己的动态 Blockstudio 区块。
编译结果会连同文件监视元数据一起缓存。编辑清单或源文件会使对应内容的缓存失效,因此下次请求就能看到更改,无需单独执行构建步骤。
WordPress 如何读取这些文件
Blockstudio 接入了 WordPress 用于主题模板的相同查找机制。在 get_block_templates() 中,基于文件的模板会像原生主题文件一样,与 source: "theme" 和 origin: "theme" 一同显示;而 get_block_template( 'acme//header', 'wp_template_part' ) 会返回带有 area 的页眉部件。
查找顺序如下:
- 存储在数据库中的站点编辑器自定义内容。
- 当前主题中的原生
.html文件。 - 基于文件的 Blockstudio 源。
- 父主题或插件的回退项。
这个顺序保留了站点编辑器的工作流程。用户编辑页脚并保存时,WordPress 会存储一个 wp_template_part 文章,而 get_block_template() 会通过 source: "custom" 返回这项自定义内容。
只要自定义内容存在,之后对 parts/footer/index.html 的更改就不会显示。用户重置部件或删除文章后,查找机制会回退到文件,并再次返回最新编译的源文件。
Blockstudio 不会将站点编辑器中的修改写回文件。如果用户的更改应成为新的默认内容,请将其复制到源文件中,然后重置自定义内容。
嵌套 index.html 和 slug
WordPress 会递归发现 templates/ 和 parts/ 中的 .html 文件。因此,使用 index.html 的清单文件夹(例如 parts/footer/index.html)也会作为原生部件显示,其 slug 根据路径生成:footer/index。由于 Blockstudio 7.6.6,由清单管理的 index.html 只会通过其声明的 slug 暴露,因此站点编辑器只会列出一个页脚,而不是两个。没有清单的嵌套 .html 文件会保持原样。
使用 PHP 检查模板
Blockstudio\Site_Templates 类会读取并编译源文件,适用于测试和部署检查:
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
每项都包含 slug、title、description、type(wp_template 或 wp_template_part)、status、source_type、postTypes(模板)或 area(部件)、meta,以及编译后的 content。传入列表即可只编译选定项目,并使用 selection_errors() 查看这些项目的问题:
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
添加其他文件夹
若要将 Blockstudio 源与原生模板分开,或从插件中提供这些源,请使用筛选器添加发现根目录:
add_filter( 'blockstudio/site_templates/template_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
} );
add_filter( 'blockstudio/site_templates/part_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
} );
blockstudio/site_templates/template_content 和 part_content 筛选器会在解析前调整源文件,blockstudio/site_templates/parser 则会为单个项目替换解析器。完整列表请参见站点模板钩子表。
如何选择
模板不会创建文章,页面才会。例如,文档分区是一组页面,其文章通过你仍可在此编写的模板来渲染。