跳转到正文

构建区块库

区块库是一组各自独立的分区区块,可组合成完整页面。每个区块都包含自己的架构、模板和样式。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 如何处理你的主题。每个主题的配置都相同:

JSON
{
	"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 特定内容:

PHP
<!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 指令。这是设计系统的核心。

CSS
/*
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 等。

对于浅色主题,反转这些值:

CSS
@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 编辑器才能将其应用:

CSS
body {
	@apply bg-bg font-sans text-white antialiased;
}

基础层用于设置元素默认样式:

CSS
@layer base {
	section {
		@apply relative overflow-hidden;
	}

	h1, h2, h3 {
		text-wrap: balance;
	}

	p {
		text-wrap: pretty;
	}
}

自定义实用类用于创建可重复使用的模式。每个主题都会定义一个 container 实用类,以统一分区间距,通常还会定义 card、badge 和按钮实用类:

CSS
@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 声明这些类:

CSS
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");

这样会告知 Tailwind 将这些类包含在输出中,即使它们只出现在未被扫描的 PHP 文件中。

分区模式

分区模式是 Blockstudio 区块库中最重要的约定。它通过两种共享机制:自定义字段和 PHP 辅助函数,为每个区块提供统一的间距、背景切换和内边距控制。

分区字段

创建一个共享字段定义,供每个区块引用:

JSON
{
	"$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
<?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 处理器:

PHP
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 定义将无法用于区块模板。

第一个区块:主视觉区

主视觉区展示了完整的区块模式。先从架构开始:

JSON
{
	"$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
<?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>

模板遵循一致的模式:

  1. 调用分区辅助函数以获取 CSS 类
  2. 外层 <section>,包含 useBlockProps 和分区类
  3. 内层 <div>,包含容器类
  4. 根据 $a 渲染内容(属性简写形式)
  5. 对可选字段进行条件渲染
  6. 正确转义:文本使用 esc_html(),URL 使用 esc_url(),属性使用 esc_attr()

添加重复器:特性网格

重复器允许客户添加、删除和重新排列条目。特性网格是典型示例:

JSON
{
	"$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
<?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 组件。占位符会在编辑器中显示一个拖放区域:

JSON
{
	"id": "image",
	"type": "files",
	"label": "Image"
}

在模板中,使用 wp_get_attachment_image() 渲染图像;未选择图像时则显示占位符 SVG:

PHP
<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()。两者都接受一个变体参数:

PHP
blockstudio_placeholder_dark( 'dashboard' )  // Dashboard mockup
blockstudio_placeholder_dark( 'chart' )      // Chart illustration
blockstudio_placeholder_dark( 'product' )    // Product shot

组合页面

页面使用 <block> 语法将区块组合成完整布局。创建主页:

JSON
{
	"name": "home",
	"title": "Home",
	"slug": "home",
	"postType": "page",
	"postStatus": "publish",
	"templateLock": "all"
}
PHP
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>

就是这样。每个 <block> 元素都会插入区块,并使用其默认属性值。运行 wp bs pages sync,将页面源应用到 WordPress。

若要覆盖特定页面的默认值,请直接传入属性:

PHP
<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)
内容 交替排列的文本 + 图像行 包含标题 + 描述 + 图像的重复器
展示 带说明文字的全宽图像 标题、描述、图像
团队 团队成员网格 标题、包含姓名 + 职务 + 图像的重复器
统计数据 关键指标 包含数字 + 标签的重复器

每个区块都遵循相同的模式:选项卡(内容 + 分区)、用于组织字段的组、用于列表的重复器,以及用于统一间距的分区辅助函数。构建两三个区块后,添加更多区块就是重复操作。

添加更多页面

随着库不断扩展,你可以使用相同的区块组合出不同页面:

PHP
<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>
PHP
<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>

相同的区块可用于多个页面,每个页面采用不同的默认值。这就是库模式的优势:只需构建一次区块,就能按需将它们组合到任意数量的页面中。

后续步骤