用 3 个文件创建自定义区块
无需JavaScript,无需构建步骤,也没有样板代码。
在JSON中定义字段
在block.json中添加blockstudio键。定义带有text、toggle和color等类型的属性。Blockstudio会自动生成编辑器UI,提供27种字段类型,从文本输入框到重复器和代码编辑器,还支持你自行注册的字段类型。
完整的JSON Schema 支持可在VS Code、PhpStorm和所有兼容的编辑器中提供自动补全和验证。
每个字段都可以为新建区块设置一个 default,以及一个在字段为空时传递给模板的 fallback。
{
"name": "starter/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading" },
{ "id": "showCta", "type": "toggle", "label": "Show CTA" },
{ "id": "background", "type": "color", "label": "Background" }
]
}
}三文件工作流
block.json用于字段,一个模板用于标记,还可选配一个样式表。
React用于PHP
RichText、InnerBlocks 和useBlockProps可直接用于PHP、Twig或Blade。
SCSS和Tailwind
使用 CSS、SCSS 或 Tailwind。SCSS 支持导入路径和共享前导代码;编辑嵌套的局部模板时,所有导入它的文件都会重新编译。
27 种字段类型
文本、颜色、图像、重复器、选择框、代码编辑器等,都在JSON中配置。
JSON Schema
在VS Code、PhpStorm和兼容的编辑器中提供自动补全和验证。
三种模板语言
PHP、Twig和Blade共用相同的变量和组件。
npm导入
在script.js中导入软件包;生产环境使用本地版本,编辑器中则由CDN提供支持。
Interactivity API
只需设置一个标志,即可启用WordPress Interactivity API。
React组件用于PHP模板
在一个模板中使用<RichText />实现内联编辑和静态前端HTML,使用<InnerBlocks />处理子区块,并使用useBlockProps作为包装器。
在编辑器中,它们会变成真正的React组件。在前端,它们会渲染为服务器端HTML,不会向访客发送任何JavaScript。
<div useBlockProps class="container">
<RichText
class="text-xl font-semibold"
tag="h1"
attribute="headline"
placeholder="Enter headline"
/>
<?php if ($a['showCta']): ?>
<a href="<?= esc_url($a['ctaUrl']) ?>">
<?= esc_html($a['ctaLabel']) ?>
</a>
<?php endif; ?>
<InnerBlocks class="mt-4 p-4 border" />
</div>使用PHP、Twig或Blade编写
使用你熟悉的模板语言。PHP 开箱即用;安装 Timber 后即可使用 Twig;Blade 则通过 Blockstudio\Blade_Renderer 在 illuminate/view 8 到 12 上运行。变量、组件和行为都保持一致。
所有语言中都可使用$a(属性)、$b(区块)、$c(上下文)和$innerBlocks。
Twig 模板也会接收完整的 Timber 上下文。Blade 也会渲染页面、区块样板和站点编辑器模板。较旧的 jenssegers/blade 封装器在 illuminate/view 10 及更高版本中无法运行,因此请改用 Blade_Renderer。
<div useBlockProps class="card">
<RichText tag="h2" attribute="title" placeholder="Card title" />
{% if a.image %}
<img src="{{ a.image.url|esc_url }}"
alt="{{ a.image.alt|esc_attr }}" />
{% endif %}
<div class="card__body">{{ a.description|esc_html }}</div>
<InnerBlocks allowedBlocks='["core/button"]' />
</div><div useBlockProps class="card">
<RichText tag="h2" attribute="title" placeholder="Card title" />
@if ($a['description'])
<div class="card__body">{{ $a['description'] }}</div>
@endif
<InnerBlocks allowedBlocks='["core/button"]' />
</div>条件逻辑和动态选项
使用包括==、!=、includes、empty和比较运算符在内的运算符来显示或隐藏字段。使用 OR 逻辑组合条件。
选项可以依赖其他字段。将 {attributes.post_type.value} 放入填充参数中,该字段发生变化时列表就会重新加载。添加 fetch: true,即可在编辑者输入时搜索文章。
通过 type: custom 和 blockstudio/blocks/attributes/populate 过滤器,让多个区块共用一个选项列表;还可以通过 blockstudio/blocks/conditions 注册自己的全局条件,例如购买检查。
{
"name": "starter/posts",
"title": "Posts",
"blockstudio": {
"attributes": [
{
"id": "post_type",
"type": "select",
"label": "Post type",
"options": [
{ "value": "page", "label": "Pages" },
{ "value": "post", "label": "Posts" }
]
},
{
"id": "selected_post",
"type": "select",
"label": "Post",
"populate": {
"type": "query",
"query": "posts",
"arguments": { "post_type": "{attributes.post_type.value}" }
}
},
{
"id": "style",
"type": "select",
"label": "Style",
"populate": { "type": "custom", "custom": "cardStyles" },
"conditions": [[
{ "type": "purchasedProduct", "operator": "==", "value": "yes" }
]]
}
]
}
}add_filter('blockstudio/blocks/attributes/populate', function ($options) {
$options['cardStyles'] = [
['value' => 'light', 'label' => 'Light'],
['value' => 'dark', 'label' => 'Dark'],
];
return $options;
});
add_filter('blockstudio/blocks/conditions', function ($conditions) {
$conditions['purchasedProduct'] = user_has_purchased(123) ? 'yes' : 'no';
return $conditions;
});让重复器始终易于管理
设置 min 和 max,用 default 行创建新区块,并用 minimized 折叠现有行。textMinimized 会使用该行自身的某个字段(例如名称)为折叠行添加标签。
行接受除选项卡之外的所有字段类型,包括嵌套重复器。行内的条件可通过 "context": "main" 检查行外字段;<RichText /> 和 <MediaPlaceholder /> 则可编辑单行,条件是其 attribute 指向 repeaterId[index].fieldId。
{
"name": "starter/team",
"title": "Team",
"blockstudio": {
"attributes": [
{
"id": "members",
"type": "repeater",
"label": "Team members",
"min": 1,
"max": 12,
"minimized": true,
"textMinimized": { "id": "name", "fallback": "Team member" },
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "bio", "type": "richtext", "label": "Bio" }
]
}
]
}
}<div useBlockProps class="team">
<?php foreach ($a['members'] as $index => $member): ?>
<article>
<h3><?= esc_html($member['name']) ?></h3>
<RichText
tag="p"
attribute="members[<?= $index ?>].bio"
placeholder="Short bio"
/>
</article>
<?php endforeach; ?>
</div>可复用字段集
在 field.json 中定义一次字段组,然后通过 "type": "custom/cta" 在任意区块中引用。字段会内联展开,因此模板读取它们的方式与读取其他属性相同。
使用 idStructure(例如 hero_{id})重复使用同一组字段,并通过 overrides 为每个区块修改标签、默认值或条件。block 字段类型也能对整个区块执行相同操作:它会内联展开该区块的字段,并返回其渲染后的 HTML。
{
"name": "cta",
"title": "Call to action",
"attributes": [
{ "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
{ "id": "url", "type": "link", "label": "Button URL" }
]
}{
"name": "starter/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "type": "custom/cta", "idStructure": "primary_{id}" },
{
"type": "custom/cta",
"idStructure": "secondary_{id}",
"overrides": {
"label": { "default": "Contact us" }
}
},
{
"id": "card",
"type": "block",
"block": "starter/card",
"idStructure": "card_{id}"
}
]
}
}无需构建步骤的 ES 模块
添加script.js即可将其作为 ES 模块加载。使用npm:前缀导入npm软件包,Blockstudio会在本地下载这些软件包,以供生产环境使用。
编辑器可即时预览;前端使用本地模块,无任何外部依赖,而且只会入队一次。
样式表也可以用相同方式导入。import "npm:swiper@11.0.0/swiper.min.css" 会下载文件,并按版本仅入队一次,即使多个区块都使用它也是如此。
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";
for (const el of document.querySelectorAll(".swiper")) {
new Swiper(el, {
slidesPerView: 3,
spaceBetween: 20,
loop: true,
});
}模板之外的区块标签
在 blockstudio.json 中将简短前缀映射到命名空间,或通过别名过滤器将单个标签映射到单个区块,然后由 <acme-card> 渲染 acme/card。启用 blockTags.enabled 后,可在文章内容和小工具中渲染标签,并由 allow 和 deny 模式限制范围。
data-* 属性会传递到区块的根元素;html-* 属性也会传递到那里,但不带前缀。使用 blockstudio/block_tags/builders 添加自己的标签构建器,并通过 migrate-block-tags 命令将简写改写为可移植的 <bs:acme-card> 拼写形式。
{
"blockTags": {
"enabled": true,
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
},
"deny": ["acme-ui/admin-*"]
}
}<div useBlockProps class="acme-features">
<acme-card
title="Fast"
text="Rendered on the server."
data-track="card"
/>
<ui-button label="Get started" href="/start" html-id="start" />
</div>自定义字段类型
注册自己的字段控件,并像使用内置字段一样使用它。
区块孤岛
缓存整个页面,并在访客的请求中渲染一个区块。
条件注册
仅针对某种文章类型、用户角色或其他全局条件注册区块;如果缺少所需插件或插件版本,也可以跳过注册。
文章元数据和选项
将值与区块属性一同存储在文章元数据或选项中。
条件逻辑
根据值使用相等、包含、空值检查和比较来显示字段。
动态填充
从文章、用户、术语、函数或 API 填充选项。
覆盖
将共享区块的名称与 override: true 一起设置,即可按 id 合并属性、替换文件名匹配的资源,并替换模板。Twig 模板可以使用 extends 覆盖单个区块。
变体
在 block.json 中声明预设字段值的变体,并使用 hidden 隐藏驱动这些变体的字段。
组件
为仅通过 PHP 或区块标签渲染的区块设置 component: true。它会保留字段、模板、资源和 Tailwind,但不会出现在插入器中。
内部区块规则
允许使用 namespace/*、category: 和 @theme 标记的区块,通过选择选项切换内部模板,并使用过滤器在前端移除包装器。
代码字段资源
将代码字段设置为 asset: true 后,编辑器输入内容会变成该区块的 CSS、SCSS 或 JavaScript,并通过 %selector% 限定到具体实例。
按文件名管理资源
*.view.js 仅在前端加载;global-、admin- 和 block-editor- 前缀则分别让文件在每个页面、wp-admin 中或区块编辑器中加载。
图标和区块文件夹
为区块指定自定义 SVG 或 HTML 图标,使用 blockstudio/path 过滤器调整发现路径,并通过 Blockstudio\Build::init() 添加文件夹。
ACF 和 Meta Box 值
模板会接收 $post_id,因此 get_field() 和 rwmb_get_value() 会读取编辑后的文章;保存后,refreshOn 会重新加载预览。
Query Loop 上下文
在 Query Loop 中,$block[‘context’][‘postId’] 会跟随当前条目,而 $block[‘postId’] 仍指向正在查看的文章。
WPML
wp bs wpml config 会写入用于标记可翻译文本字段的 wpml-config.xml;存储在字段中的图片也会加入 WPML 翻译任务,并附带替代文本和说明文字。
官方扩展套件
高级站点模板、AI 系统指令和私人 Discord 社区。一次购买,终身更新。
- 500+ 个网站模板
- AI 系统指令
- 终身更新
- 私有 Discord 社区