Перейти к содержимому

Создание библиотеки блоков

Библиотека блоков — это набор автономных блоков секций, из которых составляются полноценные страницы. Каждый блок отвечает за свою схему, шаблон и стили. 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"
				}
			]
		}
	]
}

Это поле появляется в панели настроек каждого блока на вкладке «Section». Клиентам доступны два параметра: включить акцентный фон и убрать нижний внутренний отступ (удобно для размещения секций вплотную друг к другу).

Помощник секции

В 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 обработчику Tailwind Blockstudio:

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 создает панель настроек с двумя вкладками: «Content» для полей блока и «Section» для общих настроек секции. Так устроены все блоки.

Поля организованы в контейнеры 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() для текста, esc_url() для 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, а если оно пустое, использует «Feature». Так панель настроек остается удобной даже при большом количестве элементов.

Массив 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. Ниже перечислены типичные типы блоков, примерно в порядке частоты использования:

Блок Описание Основные поля
Главный баннер Крупный заголовок с призывами к действию заголовок, описание, ссылки
Преимущества Сетка преимуществ заголовок, повторитель с названием и описанием
Призыв к действию Баннер с призывом к действию заголовок, описание, ссылка
Цены Сравнение тарифов заголовок, повторитель с названием, ценой и преимуществами
Отзывы Цитаты клиентов повторитель с цитатой, именем и ролью
Вопросы и ответы Аккордеон с вопросами заголовок, повторитель с вопросом и ответом
Логотипы Подборка логотипов клиентов заголовок (логотипы обычно представлены жестко заданными SVG)
Содержимое Чередующиеся строки с текстом и изображением повторитель с заголовком, описанием и изображением
Примеры работ Изображение на всю ширину с подписью заголовок, описание, изображение
Команда Сетка участников команды заголовок, повторитель с именем, ролью и изображением
Статистика Ключевые показатели повторитель с числом и подписью

Все блоки устроены одинаково: вкладки (Content + Section), группы для организации полей, повторители для списков и помощник секции для единых отступов. Когда вы создадите два или три блока, остальные добавлять будет несложно.

Добавление новых страниц

По мере расширения библиотеки собирайте разные страницы из тех же блоков:

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>

Одни и те же блоки используются на разных страницах, каждая со своими значениями по умолчанию. В этом и состоит преимущество библиотечного подхода: создайте блоки один раз и собирайте из них столько страниц, сколько нужно.

Следующие шаги