Tworzenie biblioteki bloków
Biblioteka bloków to zestaw samodzielnych bloków sekcji, które można łączyć w pełne strony. Każdy blok ma własny schemat, szablon i style. Blockstudio zapewnia strukturę: przetwarzanie Tailwind CSS, rejestrację atrybutów i synchronizację stron. Bloki tworzysz samodzielnie.
Ten przewodnik pokazuje, jak zbudować bibliotekę od podstaw, zgodnie z tą samą architekturą, która jest stosowana w setkach produkcyjnych motywów. Na koniec otrzymasz działający motyw z sekcją główną, siatką funkcji i złożoną stroną główną.
Struktura folderów
Każdy motyw Blockstudio ma taki sam układ:
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
Bloki znajdują się w blockstudio/sections/. Każdy blok to folder zawierający schemat block.json i szablon index.php. Strony znajdują się w pages/ i składają bloki przy użyciu składni <block>.
Pliki podstawowe
blockstudio.json
Ten plik określa, jak Blockstudio przetwarza motyw. Konfiguracja jest taka sama dla każdego motywu:
{
"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 usuwa domyślne style bloków WordPress. fullWidth sprawia, że typy wpisów page rozciągają się na całą szerokość. canvas włącza tryb obszaru roboczego edytora, zapewniając wygodniejszą edycję.
Pole tailwind.config celowo pozostawiono puste. Przy użyciu Tailwind v4 cała konfiguracja znajduje się w style.css i wykorzystuje podejście stawiające CSS na pierwszym miejscu.
index.php
Główny szablon WordPress. To standardowy WordPress, niezależny od 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>
Dodaj header.php i footer.php, jeśli potrzebujesz nawigacji. Na razie wystarczy minimalny szablon do renderowania bloków.
Tokeny projektu
Całe motywowanie odbywa się w style.css przy użyciu dyrektywy Tailwind v4 @theme. To podstawa systemu projektowego.
/*
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;
}
Każdy motyw potrzebuje co najmniej:
| Token | Zastosowanie |
|---|---|
--font-sans lub --font-serif |
Podstawowy krój pisma |
--color-bg |
Tło strony |
--color-elevated |
Tło karty/powierzchni |
--color-subtle |
Obramowania, separatory |
--color-muted |
Tekst drugorzędny |
--color-accent |
Podstawowy kolor marki |
Te tokeny automatycznie generują narzędzia Tailwind. --color-accent staje się bg-accent, text-accent, border-accent i tak dalej.
W jasnym motywie zmień wartości na przeciwne:
@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;
}
Style podstawowe i narzędzia
Pod blokiem @theme dodaj style elementów body, domyślne style warstwy bazowej i własne narzędzia.
Style elementu body muszą znajdować się poza @layer, aby przejął je edytor WordPress:
body {
@apply bg-bg font-sans text-white antialiased;
}
Warstwa bazowa dla domyślnych stylów elementów:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Własne narzędzia do wielokrotnego użytku. Każdy motyw definiuje narzędzie container, które zapewnia jednakowe odstępy między sekcjami, a zwykle także card, badge i narzędzia do przycisków:
@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);
}
}
Selektory pseudoelementów umieszczaj wewnątrz bloku @utility przy użyciu zagnieżdżania CSS (&:hover). Nigdy nie umieszczaj ich w nazwie narzędzia. @utility btn-primary:hover {} jest nieprawidłowe i zostanie odrzucone przez Tailwind.
@source wbudowany
Blockstudio automatycznie skanuje szablony bloków w poszukiwaniu klas Tailwind. Nie skanuje jednak klas użytych poza szablonami bloków (w functions.php, header.php, index.php). Zadeklaruj je za pomocą @source inline:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
Dzięki temu Tailwind uwzględni te klasy w wyniku, mimo że występują tylko w nieskanowanych plikach PHP.
Wzorzec sekcji
Wzorzec sekcji to najważniejsza konwencja w bibliotece bloków Blockstudio. Zapewnia każdemu blokowi spójne odstępy, przełączanie tła i kontrolę dopełnienia za pomocą dwóch wspólnych mechanizmów: własnego pola i funkcji pomocniczej PHP.
Pole sekcji
Utwórz wspólną definicję pola, z której mogą korzystać wszystkie bloki:
{
"$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"
}
]
}
]
}
To pole pojawia się w panelu inspektora każdego bloku na karcie „Sekcja”. Klienci mają do dyspozycji dwie kontrolki: włączanie tła akcentowego i usuwanie dolnego dopełnienia (przydatne przy układaniu sekcji jedna pod drugą bez przerw).
Funkcja pomocnicza sekcji
W functions.php utwórz funkcję pomocniczą, która zamienia te atrybuty na klasy 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 );
}
Szablon każdego bloku wywołuje tę funkcję pomocniczą w pierwszym wierszu. Zwraca ona dwa ciągi klas: jeden dla zewnętrznego elementu <section> i jeden dla wewnętrznego kontenera <div>.
Filtr konfiguracji Tailwind
Również w functions.php dodaj filtr, który przekazuje style.css do procesora Tailwind z 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 '';
}
);
Dzięki temu Blockstudio użyje style.css jako źródła konfiguracji Tailwind v4. Bez tego tokeny @theme i definicje @utility nie byłyby dostępne w szablonach bloków.
Twój pierwszy blok: sekcja główna
Sekcja główna prezentuje pełny wzorzec bloku. Zacznij od schematu:
{
"$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" }
]
}
]
}
]
}
}
Najważniejsze wzorce:
Kontener tabs tworzy inspektor z dwiema kartami: „Treść” dla pól bloku i „Sekcja” dla wspólnych ustawień sekcji. Wszystkie bloki korzystają z tej struktury.
Pola są zorganizowane w kontenery group. Grupy oddzielają wizualnie powiązane pola w inspektorze. Pierwsza grupa zawiera pola tekstowe, druga pola linków.
Wartości domyślne zapewniają przydatną treść, dzięki czemu blok wygląda na kompletny od razu po wstawieniu. Ma to kluczowe znaczenie przy komponowaniu stron, gdy bloki dodaje się bez udziału użytkownika.
Teraz szablon:
<?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>
Szablon wykorzystuje spójny wzorzec:
- Wywołaj funkcję pomocniczą sekcji, aby uzyskać klasy CSS
- Zewnętrzny element
<section>zuseBlockPropsi klasami sekcji - Wewnętrzny element
<div>z klasami kontenera - Treść wyrenderowana z
$a(skrócona składnia atrybutów) - Warunkowe renderowanie pól opcjonalnych
- Prawidłowe escapowanie:
esc_html()dla tekstu,esc_url()dla URL-i,esc_attr()dla atrybutów
Dodawanie pól powtarzalnych: siatka funkcji
Pola powtarzalne pozwalają klientom dodawać, usuwać i zmieniać kolejność elementów. Klasycznym przykładem jest siatka funkcji:
{
"$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" }
]
}
]
}
]
}
}
Właściwość textMinimized określa, jaki tekst jest wyświetlany po zwinięciu wiersza pola powtarzalnego. Pobiera wartość pola title, a jeśli jest puste, wyświetla „Funkcja”. Dzięki temu inspektor pozostaje czytelny przy dużej liczbie elementów.
Tablica default zawiera początkowe elementy, wyświetlane po pierwszym wstawieniu bloku. Zawsze ustawiaj realistyczne wartości domyślne, aby blok od razu wyglądał na kompletny.
<?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>
Dostęp do elementów pola powtarzalnego uzyskuje się przez zwykłą tablicę PHP. Iteruj za pomocą foreach, a do pól każdego elementu odwołuj się przez ich id.
Obrazy i symbole zastępcze
W blokach zawierających obrazy użyj typu pola files i komponentu MediaPlaceholder. Symbol zastępczy wyświetla w edytorze obszar, do którego można przeciągać i upuszczać pliki:
{
"id": "image",
"type": "files",
"label": "Image"
}
W szablonie renderuj obraz za pomocą wp_get_attachment_image(), a gdy nie wybrano obrazu, wyświetl zastępczy 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() zwraca wbudowany kod SVG, który używa currentColor ze zmienną --color-accent, dzięki czemu automatycznie dopasowuje się do motywu. W jasnych motywach użyj blockstudio_placeholder_light(). Oba warianty przyjmują argument wariantu:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Komponowanie stron
Strony składają się z bloków tworzących pełne układy przy użyciu składni <block>. Utwórz stronę główną:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
To wszystko. Każdy element <block> wstawia blok z domyślnymi wartościami atrybutów. Uruchom wp bs pages sync, aby zastosować źródło strony do WordPress.
Aby zastąpić wartości domyślne na konkretnej stronie, przekaż atrybuty bezpośrednio:
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
Gdy dla templateLock ustawiono wartość "all", klienci nie mogą dodawać, usuwać ani zmieniać kolejności bloków. Struktura strony jest zablokowana zgodnie z szablonem. Informacje o innych trybach blokowania i kontrolkach edycji znajdziesz na stronie Strony.
Rozbudowa biblioteki
Minimalna biblioteka zaczyna się od 3–5 bloków. Kompleksowa biblioteka zawiera 8–14 bloków. Oto typowe rodzaje bloków, w przybliżeniu uporządkowane według częstotliwości występowania:
| Blok | Opis | Kluczowe pola |
|---|---|---|
| Sekcja główna | Duży nagłówek z wezwaniami do działania | nagłówek, opis, linki |
| Funkcje | Siatka korzyści | nagłówek, pole powtarzalne z tytułem i opisem |
| CTA | Baner z wezwaniem do działania | nagłówek, opis, link |
| Cennik | Porównanie planów | nagłówek, pole powtarzalne z nazwą, ceną i funkcjami |
| Opinie | Cytaty klientów | pole powtarzalne z cytatem, imieniem i rolą |
| FAQ | Rozwijana lista pytań | nagłówek, pole powtarzalne z pytaniem i odpowiedzią |
| Logotypy | Zestaw logotypów klientów | nagłówek (logotypy są zwykle zapisane na stałe jako pliki SVG) |
| Treść | Naprzemienne wiersze tekstu i obrazu | pole powtarzalne z nagłówkiem, opisem i obrazem |
| Prezentacja | Obraz na całą szerokość z podpisem | nagłówek, opis, obraz |
| Zespół | Siatka członków zespołu | nagłówek, pole powtarzalne z imieniem, rolą i obrazem |
| Statystyki | Kluczowe dane | pole powtarzalne z liczbą i etykietą |
Każdy blok opiera się na tym samym wzorcu: karty (Treść i Sekcja), grupy porządkujące pola, pola powtarzalne dla list oraz funkcja pomocnicza sekcji zapewniająca spójne odstępy. Po zbudowaniu dwóch lub trzech bloków dodawanie kolejnych staje się rutynowe.
Dodawanie kolejnych stron
W miarę rozrastania się biblioteki twórz różne strony z tych samych bloków:
<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>
Te same bloki mogą służyć na wielu stronach, a każda z nich może mieć inne wartości domyślne. Na tym polega zaleta podejścia opartego na bibliotece: zbuduj bloki raz, a potem łącz je na dowolnej liczbie stron.
Następne kroki
- Rejestrowanie atrybutów: pełna dokumentacja typów i właściwości pól
- Typy pól: wszystkie dostępne typy pól
- Przykłady wzorców pól: grupy warunkowe, inteligentne listy wyboru i przepisy na pola powtarzalne
- Strony: blokowanie szablonów, tryby edycji i scalanie po kluczach
- Tworzenie stron opartych na plikach: praktyczny przewodnik po szablonach stron i synchronizacji
- Interaktywność: dodawanie zachowania po stronie klienta do bloków