Створення бібліотеки блоків
Бібліотека блоків — це набір автономних блоків секцій, які компонуються в повноцінні сторінки. Кожен блок має власну схему, шаблон і стилі. 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 за допомогою директиви @theme з Tailwind v4. Це основа вашої дизайн-системи.
/*
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 на обробку Tailwind у Blockstudio:
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()для тексту,esc_url()для 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>
Ті самі блоки підходять для кількох сторінок із різними значеннями за замовчуванням. У цьому й полягає перевага підходу з бібліотекою: створіть блоки один раз і компонуватимете з них стільки сторінок, скільки потрібно.
Наступні кроки
- Реєстрація атрибутів: повний довідник типів і властивостей полів
- Типи полів: усі доступні типи полів
- Збірник шаблонів полів: умовні групи, розумні списки вибору й приклади повторювачів
- Сторінки: блокування шаблонів, режими редагування й об’єднання за ключами
- Створення сторінок на основі файлів: практичний посібник зі шаблонів сторінок і синхронізації
- Інтерактивність: додавання поведінки на боці клієнта до блоків