构建区块库
区块库是一组各自独立的分区区块,可组合成完整页面。每个区块都包含自己的架构、模板和样式。Blockstudio 提供框架:Tailwind CSS 处理、属性注册和页面同步。区块由你来提供。
本指南将介绍如何从头构建一个库,并采用数百个生产主题中使用的相同架构。完成后,你将拥有一个可用的主题,其中包含主视觉区、特性网格和组合而成的主页。
文件夹结构
每个 Blockstudio 主题都遵循相同的布局:
my-theme/
├── style.css # WordPress header + Tailwind v4 config
├── blockstudio.json # Blockstudio settings
├── functions.php # Section helper + Tailwind filter
├── index.php # Main WordPress template
├── blockstudio/
│ ├── fields/
│ │ └── section/
│ │ └── field.json # Shared section controls
│ └── sections/
│ ├── hero/
│ │ ├── block.json
│ │ └── index.php
│ └── features/
│ ├── block.json
│ └── index.php
└── pages/
└── home/
├── page.json
└── index.php
区块位于 blockstudio/sections/ 中。每个区块都是一个文件夹,包含 block.json 架构和 index.php 模板。页面位于 pages/ 中,并使用 <block> 语法组合区块。
基础文件
blockstudio.json
此文件用于配置 Blockstudio 如何处理你的主题。每个主题的配置都相同:
{
"assets": {
"enqueue": true,
"reset": {
"enabled": true,
"fullWidth": ["page"]
},
"minify": { "css": true, "js": true },
"process": { "scss": false, "scssFiles": true }
},
"tailwind": {
"enabled": true,
"config": ""
},
"dev": {
"canvas": { "enabled": true }
},
"$schema": "https://blockstudio.dev/schema/blockstudio"
}
reset 会移除默认的 WordPress 区块样式。fullWidth 会让 page 文章类型延展至全宽。canvas 会启用编辑器画布模式,让编辑体验更加清爽。
tailwind.config 字段有意留空。使用 Tailwind v4 时,所有配置都位于 style.css 中,采用以 CSS 为先的方式。
index.php
主 WordPress 模板。这是标准的 WordPress,不包含任何 Blockstudio 特定内容:
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>
<main>
<?php
if ( have_posts() ) {
while ( have_posts() ) {
the_post();
the_content();
}
}
?>
</main>
<?php wp_footer(); ?>
</body>
</html>
需要导航时再添加 header.php 和 footer.php。现在,使用最简模板就足以渲染区块。
设计令牌
所有主题设置都在 style.css 中完成,使用 Tailwind v4 的 @theme 指令。这是设计系统的核心。
/*
Theme Name: My Theme
Theme URI: https://example.com
Description: A clean theme built with Blockstudio.
Version: 1.0.0
Requires at least: 6.0
Requires PHP: 8.2
Author: Your Name
Text Domain: my-theme
*/
@theme {
--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
--color-bg: #050505;
--color-elevated: #111111;
--color-subtle: rgb(255 255 255 / 0.06);
--color-muted: #888888;
--color-accent: #6366f1;
--color-accent-hover: #4f46e5;
}
每个主题至少需要:
| 令牌 | 用途 |
|---|---|
--font-sans 或 --font-serif |
主字体 |
--color-bg |
页面背景 |
--color-elevated |
卡片/表面背景 |
--color-subtle |
边框、分隔线 |
--color-muted |
次要文本 |
--color-accent |
品牌主色 |
这些令牌会自动生成 Tailwind 实用类。--color-accent 会变为 bg-accent、text-accent、border-accent 等。
对于浅色主题,反转这些值:
@theme {
--font-serif: 'Zilla Slab', serif;
--font-sans: 'DM Sans', sans-serif;
--color-bg: #f5f0e8;
--color-elevated: #ece6da;
--color-heading: #2c1810;
--color-body: #6b5c4f;
--color-muted: #9a8b7d;
--color-accent: #2d5016;
--color-subtle: #d9d1c4;
}
基础样式和实用类
在 @theme 区块下方,添加 body 样式、基础层默认值和自定义实用类。
Body 样式必须位于 @layer 之外,这样 WordPress 编辑器才能将其应用:
body {
@apply bg-bg font-sans text-white antialiased;
}
基础层用于设置元素默认样式:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
自定义实用类用于创建可重复使用的模式。每个主题都会定义一个 container 实用类,以统一分区间距,通常还会定义 card、badge 和按钮实用类:
@utility container-px {
@apply mx-auto max-w-5xl px-6;
}
@utility container {
@apply container-px py-24 sm:py-32;
}
@utility container-no-pb {
@apply pb-0 sm:pb-0;
}
@utility card {
@apply rounded-2xl border border-subtle bg-elevated/80 p-8 transition-all duration-300;
&:hover {
border-color: rgb(255 255 255 / 0.1);
}
}
@utility badge {
@apply inline-flex items-center gap-2 rounded-full border border-subtle bg-white/5 px-3.5 py-1.5 text-sm text-muted;
}
@utility btn-primary {
@apply inline-flex items-center gap-2 rounded-full bg-accent px-6 py-3 text-sm font-medium text-white transition-colors;
&:hover {
@apply bg-accent-hover;
}
}
@utility btn-secondary {
@apply inline-flex items-center gap-2 rounded-full border border-subtle px-6 py-3 text-sm font-medium text-white transition-all;
&:hover {
border-color: rgb(255 255 255 / 0.15);
background: rgb(255 255 255 / 0.04);
}
}
伪选择器应放在 @utility 区块内,并使用 CSS 嵌套(&:hover)。绝不要将它们写在实用类名称中。@utility btn-primary:hover {} 无效,会被 Tailwind 拒绝。
@source 内联
Blockstudio 会自动扫描区块模板中的 Tailwind 类。但模板以外使用的类(在 functions.php、header.php、index.php 中)不会被扫描。请使用 @source inline 声明这些类:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
这样会告知 Tailwind 将这些类包含在输出中,即使它们只出现在未被扫描的 PHP 文件中。
分区模式
分区模式是 Blockstudio 区块库中最重要的约定。它通过两种共享机制:自定义字段和 PHP 辅助函数,为每个区块提供统一的间距、背景切换和内边距控制。
分区字段
创建一个共享字段定义,供每个区块引用:
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "section",
"title": "Section",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "removeBottomPadding",
"type": "toggle",
"label": "Remove bottom padding"
},
{
"id": "accentBg",
"type": "toggle",
"label": "Accent background"
}
]
}
]
}
此字段会显示在每个区块检查器的“分区”选项卡下。客户可以使用两个控件:切换强调背景,以及移除底部内边距(便于无间隙地堆叠分区)。
分区辅助函数
在 functions.php 中创建一个辅助函数,将这些属性转换为 CSS 类:
<?php
/**
* My Theme functions.
*
* @package My_Theme
*/
/**
* Returns section and container class strings based on block attributes.
*
* @param array $a Block attributes.
* @param string $extra_section Additional classes for the section element.
* @param string $extra_container Additional classes for the container element.
* @return array Array of [ section_classes, container_classes ].
*/
function mytheme_section_classes( array $a, string $extra_section = '', string $extra_container = '' ): array {
$section = ! empty( $a['accentBg'] ) ? 'bg-accent-tint' : 'bg-bg';
$container = 'container';
if ( ! empty( $a['removeBottomPadding'] ) ) {
$container .= ' container-no-pb';
}
if ( $extra_section ) {
$section .= ' ' . $extra_section;
}
if ( $extra_container ) {
$container .= ' ' . $extra_container;
}
return array( $section, $container );
}
每个区块模板都会将此辅助函数作为第一行调用。辅助函数会返回两个类字符串:一个用于外层 <section> 元素,另一个用于内层 <div> 容器。
Tailwind 配置筛选器
同样在 functions.php 中,添加筛选器,将你的 style.css 提供给 Blockstudio 的 Tailwind 处理器:
add_filter(
'blockstudio/settings/tailwind/config',
function () {
$style = get_stylesheet_directory() . '/style.css';
if ( file_exists( $style ) ) {
// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Reading local theme file.
return file_get_contents( $style );
}
return '';
}
);
这会告知 Blockstudio 将你的 style.css 用作 Tailwind v4 配置源。否则,你的 @theme 令牌和 @utility 定义将无法用于区块模板。
第一个区块:主视觉区
主视觉区展示了完整的区块模式。先从架构开始:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/hero",
"title": "Hero",
"category": "my-theme",
"icon": "star-filled",
"description": "Full-width hero section with heading, description, and buttons.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build beautiful websites without the complexity"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "A powerful framework that lets you create stunning designs using the WordPress editor."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "primaryButton",
"type": "link",
"label": "Primary Button",
"default": {
"title": "Get Started",
"url": "#"
}
},
{
"id": "secondaryButton",
"type": "link",
"label": "Secondary Button",
"default": {
"title": "Learn More",
"url": "#"
}
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
值得注意的关键模式:
tabs 封装器会创建两个选项卡的检查器:“内容”用于区块字段,“分区”用于共享分区控件。每个区块都使用此结构。
字段按 group 容器进行组织。组会在检查器中直观地区分相关字段。第一组包含文本字段,第二组包含链接字段。
默认值提供了有意义的内容,因此区块插入后立即显得完整。这对页面组合至关重要,因为添加区块时不会有用户交互。
现在来看模板:
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a, '', 'text-center' ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<h1 class="text-5xl font-medium tracking-tight sm:text-6xl lg:text-7xl">
<?php echo esc_html( $a['heading'] ); ?>
</h1>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-6 text-lg leading-relaxed text-muted max-w-xl mx-auto">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
<div class="mt-10 flex items-center justify-center gap-x-4">
<?php if ( ! empty( $a['primaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['primaryButton']['url'] ); ?>" class="btn-primary">
<?php echo esc_html( $a['primaryButton']['title'] ); ?>
</a>
<?php endif; ?>
<?php if ( ! empty( $a['secondaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['secondaryButton']['url'] ); ?>" class="btn-secondary">
<?php echo esc_html( $a['secondaryButton']['title'] ); ?>
</a>
<?php endif; ?>
</div>
</div>
</section>
模板遵循一致的模式:
- 调用分区辅助函数以获取 CSS 类
- 外层
<section>,包含useBlockProps和分区类 - 内层
<div>,包含容器类 - 根据
$a渲染内容(属性简写形式) - 对可选字段进行条件渲染
- 正确转义:文本使用
esc_html(),URL 使用esc_url(),属性使用esc_attr()
添加重复器:特性网格
重复器允许客户添加、删除和重新排列条目。特性网格是典型示例:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/features",
"title": "Features",
"category": "my-theme",
"icon": "grid-view",
"description": "Feature grid with titles and descriptions.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Everything you need"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "Our toolkit gives you the building blocks to go from idea to production."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "features",
"type": "repeater",
"label": "Features",
"textMinimized": {
"id": "title",
"fallback": "Feature"
},
"default": [
{
"title": "Lightning Fast",
"description": "Optimized for performance with minimal overhead."
},
{
"title": "Fully Responsive",
"description": "Every component adapts across all screen sizes."
},
{
"title": "Easy to Customize",
"description": "Adjust every detail to match your brand."
}
],
"attributes": [
{
"id": "title",
"type": "text",
"label": "Title"
},
{
"id": "description",
"type": "textarea",
"label": "Description"
}
]
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
textMinimized 属性控制重复器行折叠时显示的文本。它会读取 title 字段值;如果为空,则显示“特性”。这样在条目较多时,检查器仍然易于使用。
default 数组提供初始条目。这些条目会在区块首次插入时显示。请始终提供符合实际的默认值,让区块立即显得完整。
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<?php if ( ! empty( $a['heading'] ) ) : ?>
<div class="text-center max-w-2xl mx-auto">
<h2 class="text-3xl font-medium tracking-tight sm:text-4xl">
<?php echo esc_html( $a['heading'] ); ?>
</h2>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-4 text-base leading-relaxed text-muted">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
</div>
<?php endif; ?>
<?php if ( ! empty( $a['features'] ) ) : ?>
<div class="mt-16 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
<?php foreach ( $a['features'] as $feature ) : ?>
<div class="card">
<h3 class="text-sm font-medium">
<?php echo esc_html( $feature['title'] ); ?>
</h3>
<p class="mt-2 text-sm leading-relaxed text-muted">
<?php echo esc_html( $feature['description'] ); ?>
</p>
</div>
<?php endforeach; ?>
</div>
<?php endif; ?>
</div>
</section>
重复器条目以普通的 PHP 数组形式访问。使用 foreach 循环,并通过各字段的 id 访问字段。
图像和占位符
对于包含图像的区块,请使用 files 字段类型和 MediaPlaceholder 组件。占位符会在编辑器中显示一个拖放区域:
{
"id": "image",
"type": "files",
"label": "Image"
}
在模板中,使用 wp_get_attachment_image() 渲染图像;未选择图像时则显示占位符 SVG:
<div class="overflow-hidden rounded-2xl bg-elevated">
<MediaPlaceholder attribute="image" allowedTypes="<?php echo esc_attr( wp_json_encode( array( 'image' ) ) ); ?>" />
<?php if ( ! empty( $a['image'] ) ) : ?>
<?php echo wp_get_attachment_image( $a['image'][0]['ID'], 'full', false, array( 'class' => 'block w-full' ) ); ?>
<?php else : ?>
<?php echo blockstudio_placeholder_dark(); ?>
<?php endif; ?>
</div>
blockstudio_placeholder_dark() 会返回一个内嵌 SVG,其中使用 currentColor 和 --color-accent 变量,因此会自动适配你的主题。浅色主题请使用 blockstudio_placeholder_light()。两者都接受一个变体参数:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
组合页面
页面使用 <block> 语法将区块组合成完整布局。创建主页:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
就是这样。每个 <block> 元素都会插入区块,并使用其默认属性值。运行 wp bs pages sync,将页面源应用到 WordPress。
若要覆盖特定页面的默认值,请直接传入属性:
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
将 templateLock 设置为 "all" 后,客户无法添加、删除或重新排列区块。页面结构会锁定为你的模板。有关其他锁定模式和编辑控件,请参阅页面。
扩展规模
一个精简的库从 3-5 个区块开始,完整的库则有 8-14 个。以下是常见区块类型,大致按出现频率排序:
| 区块 | 描述 | 关键字段 |
|---|---|---|
| 主视觉区 | 带有 CTA 的大标题 | 标题、描述、链接 |
| 特性 | 优势网格 | 标题、包含标题 + 描述的重复器 |
| CTA | 行动号召横幅 | 标题、描述、链接 |
| 定价 | 方案对比 | 标题、包含名称 + 价格 + 特性的重复器 |
| 客户评价 | 客户引言 | 包含引言 + 姓名 + 职务的重复器 |
| 常见问题 | 问题手风琴 | 标题、包含问题 + 答案的重复器 |
| 标志 | 客户标志墙 | 标题(标志通常是硬编码的 SVG) |
| 内容 | 交替排列的文本 + 图像行 | 包含标题 + 描述 + 图像的重复器 |
| 展示 | 带说明文字的全宽图像 | 标题、描述、图像 |
| 团队 | 团队成员网格 | 标题、包含姓名 + 职务 + 图像的重复器 |
| 统计数据 | 关键指标 | 包含数字 + 标签的重复器 |
每个区块都遵循相同的模式:选项卡(内容 + 分区)、用于组织字段的组、用于列表的重复器,以及用于统一间距的分区辅助函数。构建两三个区块后,添加更多区块就是重复操作。
添加更多页面
随着库不断扩展,你可以使用相同的区块组合出不同页面:
<block name="my-theme/hero" heading="Simple, Transparent Pricing" description="Choose the plan that fits."></block>
<block name="my-theme/pricing"></block>
<block name="my-theme/faq" heading="Pricing FAQ"></block>
<block name="my-theme/cta"></block>
<block name="my-theme/hero" heading="About Us" description="Our story."></block>
<block name="my-theme/team"></block>
<block name="my-theme/testimonials"></block>
<block name="my-theme/cta" heading="Join Our Team"></block>
相同的区块可用于多个页面,每个页面采用不同的默认值。这就是库模式的优势:只需构建一次区块,就能按需将它们组合到任意数量的页面中。