跳转到正文

来自文件的站点编辑器模板和模板部件

区块主题会在 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 用于告知站点编辑器该部件所属的位置:

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Site header with logo and navigation",
  "area": "header"
}

源文件使用与 Blockstudio 页面和图案相同的语法。<div> 会变成群组区块,属性会变成区块属性,而 <block> 元素会生成任何已注册区块:

PHP
<div layout='{"type":"flex","justifyContent":"space-between"}'>
  <block name="core/site-title" />
  <block name="core/navigation" overlayMenu="mobile" />
</div>

Blockstudio 会将其编译为以下区块标记:

HTML
<!-- 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 /> 标签或已配置的标签前缀,都会编译为该区块的注释。

部件可以小到只有一个段落。这里使用 index.html 来说明源文件是标记,而不是程序:

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<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 绝不会为其添加前缀。

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<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" />

单篇文章模板采用相同结构,但使用文章区块:

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<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" />

编译后的单篇模板:

HTML
<!-- 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 列出它们适用的文章类型,编辑者就可以在模板选择器中选择这些模板:

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<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 的页眉部件。

查找顺序如下:

  1. 存储在数据库中的站点编辑器自定义内容。
  2. 当前主题中的原生 .html 文件。
  3. 基于文件的 Blockstudio 源。
  4. 父主题或插件的回退项。

这个顺序保留了站点编辑器的工作流程。用户编辑页脚并保存时,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 类会读取并编译源文件,适用于测试和部署检查:

PHP
$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() 查看这些项目的问题:

PHP
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors   = Blockstudio\Site_Templates::selection_errors( 'templates' );

添加其他文件夹

若要将 Blockstudio 源与原生模板分开,或从插件中提供这些源,请使用筛选器添加发现根目录:

PHP
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 则会为单个项目替换解析器。完整列表请参见站点模板钩子表。

如何选择

需求 使用
主题布局为某个 URL 选择的模板:页眉、页脚、单篇、归档 站点模板和部件 WordPress
内容存放在文件中的可路由页面 基于文件的页面
编辑者可插入的可复用部分 图案

模板不会创建文章,页面才会。例如,文档分区是一组页面,其文章通过你仍可在此编写的模板来渲染。

后续步骤