页面和样板
Blockstudio 让你可以在主题中将 WordPress 页面、区块样板和站点编辑器模板定义为文件。编写类似 HTML 的模板,Blockstudio 的解析器会将其转换为原生 WordPress 区块。
- 页面会作为 WordPress 文章同步到数据库,使文件模板与页面内容保持同步。
- 样板通过
register_block_pattern()在内存中注册,用户可以在区块插入器中将其放置到任意位置。 - 站点模板为 WordPress 站点编辑器提供基于文件的
wp_template和wp_template_part来源。
这三项功能共用同一个 HTML 解析器和区块语法。
实用指南:了解基于文件的页面模板、同步和锁定。
文件夹结构
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
每个子文件夹都包含一个 JSON 配置文件(page.json、pattern.json、template.json 或 part.json)和一个模板文件。
模板引擎
模板可以写成 index.php 中的纯标记,也可以使用 Twig 或 Blade:
| 文件 | 引擎 | 要求 |
|---|---|---|
index.php |
无(按原样读取,不执行 PHP 代码) | 无 |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
如果存在多个模板文件,优先顺序为:index.php > index.blade.php > index.twig。
由于模板在初始化时编译(任何请求上下文出现之前),Twig 和 Blade 模板无法访问动态变量。它们适用于内置函数和筛选器,例如 {{ "text"|upper }} 或 {{ strtoupper("text") }}。
HTML 到区块的映射
标准 HTML 元素会自动转换为对应的 WordPress 区块。
文本
| HTML | 区块 |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list(无序) |
<ol> |
core/list(有序) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
列表会保留其结构。在 <li> 中的 <ul> 或 <ol> 会成为该 core/list-item 的 core/list 内部区块,也就是编辑器保存的结构,因此列表可以任意嵌套。列表或列表项上的 class 会成为其 className,这样就能从页面文件设置区块样式,例如 is-style-checks;<block name="core/list" className="..."> 也能实现同样的效果。
媒体
| HTML | 区块 |
|---|---|
<img> |
core/image |
<figure> |
core/image(带说明文字) |
<audio> |
core/audio |
<video> |
core/video |
布局
| HTML | 区块 |
|---|---|
<div>、<section> |
core/group |
<main>、<header>、<footer>、<article>、<aside> |
core/group,保留元素作为其 tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
区块语法
对于没有直接 HTML 等效项的区块,请使用 <block> 元素:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
核心区块
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
自定义区块
同一语法适用于任何已注册的区块:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
属性
<block> 元素上的 HTML 属性会作为区块属性传入。支持 JSON 值:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
属性值只会解码一次,就像浏览器读取它们一样,因此 data-animate="[&>span]:fade" 和 data-animate="[&>span]:fade" 存储的是相同的值。
映射到 Blockstudio 区块的元素,其所有属性都会与区块一同存储。已声明的字段会传递给模板;区块未声明的全局属性(id、style、role、title、lang、dir、hidden、tabindex、aria-* 和 data-*)会在渲染时放到区块的根元素上,效果与 区块标签完全相同。在页面和样板源文件中,html- 前缀只用于指定其中一种全局属性,因此 html-role="note" 会转发为 role,而 html-onclick 等事件处理器永远不会被渲染。其余所有内容(包括未声明的 class)都会留在文章内容中,不会输出到页面;wp bs pages sync 会针对其解析的每个页面报告这些内容。
自定义区块渲染器
HTML 解析器采用基于注册表的架构。使用 blockstudio/block_tags/builders 为自定义区块添加构建器:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
然后在任意模板中使用它:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
你也可以覆盖核心区块的渲染方式:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
构建器回调会接收解析后的属性和原始内部内容。它们必须返回一个 WordPress 区块数组。完整的筛选器顺序和容器示例请参阅 自定义渲染器。
构建器函数签名
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
元素映射
默认情况下,<h1>、<p> 和 <img> 等标准 HTML 元素会映射到核心 WordPress 区块。你可以使用 blockstudio/parser/element_mapping 筛选器覆盖此映射,将任意 HTML 元素指向其他区块:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
启用此筛选器后,模板中的每个 <h1> 都会生成 custom/heading 区块,而不是 core/heading。元素属性会传递给目标区块。如果已为目标区块名称注册渲染器,就会使用该渲染器;否则会创建通用区块结构。
如果你的主题或插件提供了应在所有页面和样板模板中替代默认项的自定义区块类型,这种方式就很有用。
对于简单的 <p> 映射,Blockstudio 可以将内部 HTML 直接路由到已注册的非核心 Blockstudio 区块的 content richtext 属性。目标区块必须声明一个带有 id: "content" 和 type: "richtext" 的属性。
即使相同标签默认也映射为元素,内联格式(a、b、br、code、del、em、i、img、ins、mark、s、small、span、strong、sub、sup、u)仍会保留在路由值中,例如默认映射的 code 和 img。如果段落唯一的子元素是图片,它会变为 <img> 所映射到的区块,与 Markdown 为独立图片生成的区块相同。嵌套的区块标签和区块级 HTML 仍会解析为内部区块。
如果目标区块取决于元素属性,映射值也可以是可调用对象:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
从 <section> 和 <div> 等容器元素映射的自定义区块,会递归解析嵌套的 HTML 子元素,因此内部标题、图像、区块标签和段落都会成为原生子区块。
完整示例
组合多种区块类型的完整页面模板:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>