Изграждане на библиотека от блокове
Библиотеката от блокове е набор от самостоятелни блокове за секции, които се съчетават в цели страници. Всеки блок има собствена схема, шаблон и стилове. 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 на процесора 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 няма да са достъпни в шаблоните на блоковете.
Първият ви блок: Hero
Водещата секция показва целия шаблон за блок. Започнете със схемата:
{
"$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 блока. Ето често срещаните типове блокове, приблизително подредени според честотата им на употреба:
| Блок | Описание | Основни полета |
|---|---|---|
| Hero | Голямо заглавие с призиви за действие | заглавие, описание, връзки |
| Характеристики | Мрежа от предимства | заглавие, повторител със заглавие и описание |
| 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>
Едни и същи блокове обслужват няколко страници, всяка със свои стойности по подразбиране. В това е предимството на подхода с библиотека: изградете блоковете веднъж и ги съчетавайте в толкова страници, колкото ви трябват.
Следващи стъпки
- Регистриране на атрибути: пълен справочник за типовете и свойствата на полетата
- Типове полета: всички налични типове полета
- Наръчник с шаблони за полета: условни групи, интелигентни списъци за избор и рецепти за повторители
- Страници: заключване на шаблони, режими на редактиране и сливане по ключове
- Изграждане на страници от файлове: практическо ръководство за шаблони на страници и синхронизиране
- Интерактивност: добавяне на поведение от страна на клиента към блокове