跳转到正文

站点模板

站点模板让区块主题能够使用与 Blockstudio 页面和样式相同的文件优先语法,定义 WordPress wp_template 和 wp_template_part 源文件。

如果你想控制 WordPress 通过站点编辑器的模板层级选择的主题布局,请使用站点模板:主页、单篇文章、归档、搜索、404页面、页眉、页脚和其他模板部件。

页面、样式还是站点模板?

功能 创建内容 适用场景
页面 文章或自定义文章类型条目 实际内容页面、文档页面、落地页和可路由内容。
样式 区块样式 供编辑者插入的可复用区块。
站点模板 wp_template 和 wp_template_part 文件源 由站点编辑器和 WordPress 模板层级控制的主题布局。

站点模板不会创建常规页面。它们提供 WordPress 解析区块主题模板时使用的文件源。如果用户在站点编辑器中自定义模板,WordPress 会将该自定义内容存储在数据库中;在重置之前,数据库中的内容优先于文件源。

文件夹结构

将完整模板放在 templates/,将模板部件放在 parts/:

Text
theme/
  templates/
    front-page/
      template.json
      index.php
    single/
      template.json
      index.twig
  parts/
    header/
      part.json
      index.php
    footer/
      part.json
      index.php

每个文件夹都包含一个清单和一个源文件。

文件 引擎
index.php 类似 HTML 的区块标记,按原样读取(PHP 代码不会执行)
index.blade.php Blade
index.twig Twig
index.html 类似 HTML 的区块标记

如果存在多个源文件,Blockstudio 会按以下顺序使用:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPress 还会递归发现 .html 文件,并通常会在由路径生成的别名下公开嵌套的 index.html,例如 header/index。如果该文件属于 Blockstudio 清单,Blockstudio 会移除由路径生成的重复项,只公开清单声明的 slug。没有 Blockstudio 清单的嵌套原生 .html 模板不会改变。

源文件会被编译一次,生成原生 WordPress 区块标记。它不应依赖当前请求或当前文章。请将运行时行为放在动态区块中。

template.json

template.json 定义一个完整的站点编辑器模板。

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template",
  "postTypes": ["page"]
}

属性

属性 类型 默认值 描述
slug / name string 文件夹名称 WordPress 模板别名。使用精确的层级别名,例如 front-page、single、archive-product 或 404。
title string 别名生成的标题 站点编辑器中显示的标题。
description string "" 站点编辑器中显示的描述。
postTypes string[] [] 自定义模板的文章类型。核心层级模板可以省略此项。
source / template / file string 自动检测索引文件 相对于模板文件夹的可选源文件路径。
status string "publish" 模板状态。
sync boolean false 保留供未来数据库实体化使用。v1 中的用户自定义内容绝不会被覆盖。
meta object {} 供辅助 API 使用的自定义元数据。未知清单键也会存储在此处。

模板别名不带前缀。WordPress 需要层级使用的精确名称:

Text
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat

part.json

part.json 定义一个站点编辑器模板部件。

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Main site header",
  "area": "header"
}

属性

属性 类型 默认值 描述
slug / name string 文件夹名称 WordPress 模板部件别名。
title string 别名生成的标题 站点编辑器中显示的标题。
description string "" 站点编辑器中显示的描述。
area string "uncategorized" 模板部件区域。常见值包括 header、footer 和 sidebar。
source / template / file string 自动检测索引文件 相对于部件文件夹的可选源文件路径。
status string "publish" 模板部件状态。
meta object {} 供辅助 API 使用的自定义元数据。未知清单键也会存储在此处。

编写标记

站点模板源文件使用与页面和样式相同的解析器:

PHP
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <p>This template is compiled from Blockstudio files.</p>
    <block name="core/post-content" />
  </main>

  <block name="core/template-part" slug="footer" />
</div>

<main> 元素会变成一个 core/group 区块,渲染为 <main>;其子元素(包括 core/post-content 区块标签)会变成内部区块。你可以使用:

  • 标准 HTML 元素,例如 <h1>、<p>、<ul>、<div>,以及分节元素 <main>、<header>、<footer>、<article> 和 <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • 已配置的区块标签前缀
  • Blockstudio 区块和组件

WordPress 渲染编译后的模板时,模板部件区块会接收当前主题属性。

站点编辑器自定义项

Blockstudio 提供文件源。WordPress 负责管理用户自定义项。

查找顺序如下:

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

用户在站点编辑器中保存 Blockstudio 基于文件的模板时,WordPress 会在数据库中创建常规的 wp_template 或 wp_template_part 条目。此保存条目的优先级高于之后的文件变更。重置或删除自定义项后,会重新显示最新的基于文件的源。

Blockstudio 不会将站点编辑器中的修改写回 v1 文件。

性能

模板发现会按请求缓存,并通过文件监视元数据持久化。更改清单或源文件会使缓存的编译内容失效。数据库自定义项不会被缓存覆盖:WordPress 仍会优先检查它们。

负责组合多个根目录文件的运行时集成可以为模板和模板部件提供逻辑发现源。清单和选定的源模板可以位于不同的物理根目录,同时保留统一的逻辑主题树。

PHP API

PHP
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();

$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');

$paths = Blockstudio\Site_Templates::get_paths();

传入明确列表,只读取并编译精确的别名、路径或源路径:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

省略参数会保留完整的注册表行为。传入空列表则不返回任何项。常规别名和路径请求会将发现范围缩小到匹配的目录;自定义清单别名可能需要扫描元数据,但仍不会编译或返回无关源文件。

也可以使用模板辅助函数:

PHP
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');

钩子

站点模板的完整扩展接口如下:

钩子 类型 描述
blockstudio/site_templates/template_paths 筛选器 调整完整模板的发现根目录。
blockstudio/site_templates/part_paths 筛选器 调整模板部件的发现根目录。
blockstudio/site_templates/paths 筛选器 以 templates 和 parts 的形式同时调整两组路径列表。
blockstudio/site_templates/template_candidates 筛选器 调整清单的源文件候选项。
blockstudio/site_templates/templates 筛选器 调整注册表 API 返回的模板。
blockstudio/site_templates/parts 筛选器 调整注册表 API 返回的模板部件。
blockstudio/site_templates/template_content 筛选器 调整完整模板源在解析前的编译结果。
blockstudio/site_templates/part_content 筛选器 调整模板部件源在解析前的编译结果。
blockstudio/site_templates/parser 筛选器 替换某个条目的 Html_Parser 实例。
blockstudio/site_templates/source_compiled 操作 在编译某个选定源之前立即运行。
blockstudio/site_templates/discovered 操作 在冷启动发现和编译流程后运行。
blockstudio/site_templates/registered 操作 在重建的注册表持久化后运行。

添加或替换发现路径:

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;
});

add_filter('blockstudio/site_templates/paths', function ($paths) {
    return $paths;
});

筛选已发现的数据:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

解析前筛选源文件:

PHP
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
    return $content;
}, 10, 2);

add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
    return $content;
}, 10, 2);

更改源文件候选项或解析器:

PHP
add_filter(
    'blockstudio/site_templates/template_candidates',
    function ($candidates, $directory, $manifest) {
        $candidates[] = $directory . '/template.custom.php';
        return $candidates;
    },
    10,
    3
);

add_filter(
    'blockstudio/site_templates/parser',
    function ($parser, $item) {
        return $parser;
    },
    10,
    2
);

discovered 和 registered 是用于重建缓存生命周期的操作。在注册表缓存命中时不会触发。