Blokkkönyvtár építése
A blokkkönyvtár önálló szekcióblokkok készlete, amelyek teljes oldalakká állnak össze. Minden blokkhoz saját séma, sablon és stílus tartozik. A Blockstudio biztosítja a keretrendszert: Tailwind CSS feldolgozás, attribútumregisztráció és oldalszinkronizálás. A blokkokat Ön készíti el.
Ez az útmutató végigvezet egy könyvtár nulláról történő felépítésén, a több száz éles témában használt architektúrát követve. A végére egy működő témája lesz hős szekcióval, funkciórácsokkal és összeállított kezdőlappal.
Mappastruktúra
Minden Blockstudio téma ugyanazt az elrendezést követi:
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
A blokkok a blockstudio/sections/ mappában találhatók. Minden blokk egy mappa, benne block.json sémával és index.php sablonnal. Az oldalak a pages/ mappában vannak, és a <block> szintaxissal állítják össze a blokkokat.
Alapfájlok
blockstudio.json
Ez a fájl szabályozza, hogyan dolgozza fel a Blockstudio a témát. A konfiguráció minden témánál azonos:
{
"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"
}
Az reset eltávolítja az alapértelmezett WordPress blokkstílusokat. Az fullWidth teljes szélességűre állítja a page bejegyzéstípusokat. Az canvas engedélyezi a szerkesztővászon módot a letisztultabb szerkesztési élményért.
Az tailwind.config mező szándékosan üres. Az Tailwind v4 használatával minden konfiguráció az style.css fájlban él, a CSS-központú megközelítést követve.
index.php
A fő WordPress sablon. Ez szabványos WordPress, semmi Blockstudio-specifikus nincs benne:
<!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>
Adjon hozzá egy header.php és egy footer.php elemet, ha navigációra van szüksége. Egyelőre a minimális sablon is elegendő a blokkok rendereléséhez.
Dizájn tokenek
Minden témázás a style.css fájlban történik, a Tailwind v4 @theme direktívájával. Ez a dizájnrendszer központi eleme.
/*
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;
}
Minden témának legalább ezekre van szüksége:
| Token | Rendeltetés |
|---|---|
--font-sans vagy --font-serif |
Elsődleges betűtípus |
--color-bg |
Oldal háttere |
--color-elevated |
Kártya/felület háttere |
--color-subtle |
Szegélyek, elválasztók |
--color-muted |
Másodlagos szöveg |
--color-accent |
Elsődleges márkaszín |
Ezek a tokenek automatikusan létrehozzák a Tailwind segédosztályokat. Az --color-accent értéke bg-accent, text-accent, border-accent és így tovább lesz.
Világos témához fordítsa meg az értékeket:
@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;
}
Alapstílusok és segédosztályok
Az @theme blokk után adja hozzá a törzs stílusait, az alapréteg alapértelmezéseit és az egyéni segédosztályokat.
A törzs stílusait az @layer blokkon kívül kell elhelyezni, hogy az WordPress szerkesztő is alkalmazza őket:
body {
@apply bg-bg font-sans text-white antialiased;
}
Alapréteg az elemek alapértelmezéseihez:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Egyéni segédosztályok az újrafelhasználható mintákhoz. Minden téma definiál egy container segédosztályt a következetes szekcióközökért, jellemzően továbbá card, badge és gombsegédosztályokat is:
@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);
}
}
Az ál-szelektorok az @utility blokkon belülre kerüljenek, a CSS beágyazási szintaxissal (&:hover). Soha ne tegye őket a segédosztály nevébe. Az @utility btn-primary:hover {} érvénytelen, és a Tailwind elutasítja.
@source beágyazottan
A Blockstudio automatikusan átvizsgálja a blokk sablonjait, és megkeresi bennük az Tailwind osztályokat. A blokksablonokon kívül használt osztályokat (az functions.php, header.php, index.php fájlokban) viszont nem vizsgálja át. Ezeket a @source inline segítségével deklarálja:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
Ezzel arra utasítja a Tailwind rendszert, hogy ezeket az osztályokat akkor is belefoglalja a kimenetbe, ha csak át nem vizsgált PHP fájlokban fordulnak elő.
A szekcióminta
A szekcióminta a Blockstudio blokkkönyvtár legfontosabb konvenciója. Két közös mechanizmussal biztosít egységes térközöket, váltható hátteret és szabályozható belső margót minden blokkban: egy egyéni mezővel és egy PHP segédfüggvénnyel.
A szekciómező
Hozzon létre egy közös meződefiníciót, amelyre minden blokk hivatkozhat:
{
"$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"
}
]
}
]
}
Ez a mező minden blokk szerkesztőpaneljén megjelenik egy „Szekció” fülön. Az ügyfelek két vezérlőelemet kapnak: bekapcsolhatják a kiemelő hátteret, illetve eltávolíthatják az alsó belső margót (ez hasznos a hézagmentesen egymásra illesztett szekcióknál).
A szekció-segédfüggvény
A functions.php fájlban hozzon létre egy segédfüggvényt, amely ezeket az attribútumokat CSS osztályokká alakítja:
<?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 );
}
Minden blokk sablonjának első sorában ezt a segédfüggvényt kell meghívni. Két osztálykarakterláncot ad vissza: egyet a külső <section> elemhez, egyet pedig a belső <div> konténerhez.
Tailwind konfigurációs szűrő
Szintén az functions.php fájlban adja hozzá a szűrőt, amely továbbítja a style.css tartalmát a Blockstudio Tailwind feldolgozójának:
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 '';
}
);
Ezzel arra utasítja a Blockstudio rendszert, hogy a style.css legyen a Tailwind v4 konfigurációs forrása. Enélkül a @theme tokenek és a @utility definíciók nem lennének elérhetők a blokksablonokban.
Az első blokk: Hero
A hero szekció bemutatja a teljes blokkmintát. Kezdje a sémával:
{
"$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" }
]
}
]
}
]
}
}
Figyelje meg a következő mintákat:
Az tabs burkoló kétfüles szerkesztőpanelt hoz létre: a „Tartalom” fülön találhatók a blokk mezői, a „Szekció” fülön pedig a közös szekcióvezérlők. Minden blokk ezt a szerkezetet használja.
A mezők group konténerekbe vannak rendezve. A csoportok vizuálisan különítik el az összetartozó mezőket a szerkesztőpanelen. Az első csoport szövegmezőket, a második hivatkozásmezőket tartalmaz.
Az alapértelmezett értékek értelmes tartalmat adnak, így a blokk már beillesztéskor teljesnek tűnik. Ez elengedhetetlen az oldalak összeállításánál, amikor a blokkok felhasználói beavatkozás nélkül kerülnek be.
Most jöjjön a sablon:
<?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>
A sablon következetes mintát követ:
- Hívja meg a szekció-segédfüggvényt az CSS osztályok lekéréséhez
- Külső
<section>elemuseBlockPropsattribútummal és szekcióosztályokkal - Belső
<div>elem konténerosztályokkal - Az
$a-ből renderelt tartalom (az attribútumok rövid jelölése) - Feltételes renderelés az opcionális mezőkhöz
- Helyes escape-elés:
esc_html()a szöveghez,esc_url()az URL-ekhez,esc_attr()az attribútumokhoz
Ismétlők hozzáadása: funkciórács
Az ismétlőkkel az ügyfelek elemeket adhatnak hozzá, távolíthatnak el és rendezhetnek át. A funkciórács klasszikus példa erre:
{
"$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" }
]
}
]
}
]
}
}
Az textMinimized tulajdonság szabályozza, milyen szöveg látható összecsukott ismétlősornál. Az title mező értékét olvassa be, üres érték esetén pedig a „Funkció” szót jeleníti meg. Ez sok elem esetén is használhatóvá teszi a szerkesztőpanelt.
Az default tömb adja meg a kezdeti elemeket. Ezek a blokk első beillesztésekor jelennek meg. Mindig reális alapértékeket adjon meg, hogy a blokk azonnal teljesnek tűnjön.
<?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>
Az ismétlőelemek egyszerű PHP tömbként érhetők el. A bejáráshoz használja a foreach elemet, az egyes elemek mezőit pedig a id alapján érheti el.
Képek és helyőrzők
Képeket tartalmazó blokkoknál használja az files mezőtípust és az MediaPlaceholder komponenst. A helyőrző fogd és vidd területet jelenít meg a szerkesztőben:
{
"id": "image",
"type": "files",
"label": "Image"
}
A sablonban az wp_get_attachment_image() segítségével jelenítse meg a képet, és mutasson helyőrző SVG-t, ha nincs kiválasztott kép:
<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>
Az blockstudio_placeholder_dark() olyan beágyazott SVG-t ad vissza, amely az currentColor elemet használja az --color-accent változóval, így automatikusan alkalmazkodik a témához. Világos témához használja ezt: blockstudio_placeholder_light(). Mindkettő elfogad egy változatot megadó argumentumot:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Oldalak összeállítása
Az oldalakon a <block> szintaxissal állíthat össze teljes elrendezéseket a blokkokból. Hozzon létre egy kezdőlapot:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
Ennyi az egész. Minden <block> elem beilleszti a blokkot az alapértelmezett attribútumértékeivel. Futtassa ezt: wp bs pages sync, hogy az oldal forrását alkalmazza erre: WordPress.
Ha egy adott oldalnál felül szeretné írni az alapértékeket, közvetlenül adja meg az attribútumokat:
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
Ha az templateLock értéke "all", az ügyfelek nem adhatnak hozzá, nem távolíthatnak el és nem rendezhetnek át blokkokat. Az oldalszerkezetet a sablon rögzíti. A többi zárolási módról és szerkesztési vezérlőről a Pages oldalon olvashat.
Bővítés
Egy minimális könyvtár 3-5 blokkal indul. Egy átfogó könyvtárban 8-14 blokk van. Íme a gyakori blokktípusok, nagyjából előfordulásuk gyakorisága szerinti sorrendben:
| Blokk | Leírás | Fő mezők |
|---|---|---|
| Hero | Nagy címsor CTA-kkal | címsor, leírás, hivatkozások |
| Funkciók | Előnyök rácsos elrendezésben | címsor, ismétlő címmel és leírással |
| CTA | Cselekvésre ösztönző banner | címsor, leírás, hivatkozás |
| Árazás | Csomagok összehasonlítása | címsor, ismétlő névvel, árral és funkciókkal |
| Vélemények | Ügyfélidézetek | ismétlő idézettel, névvel és szerepkörrel |
| GYIK | Kérdések harmonikaszerű listája | címsor, ismétlő kérdéssel és válasszal |
| Logók | Ügyfelek logóinak felhője | címsor (a logók jellemzően rögzített SVG-k) |
| Tartalom | Váltakozó szöveg- és képsorok | ismétlő címsorral, leírással és képpel |
| Bemutató | Teljes szélességű kép felirattal | címsor, leírás, kép |
| Csapat | Csapattagok rácsos elrendezésben | címsor, ismétlő névvel, szerepkörrel és képpel |
| Statisztikák | Fő mérőszámok | ismétlő számmal és címkével |
Minden blokk ugyanazt a mintát követi: fülek (Tartalom + Szekció), csoportok a rendszerezéshez, ismétlők a listákhoz és a szekció-segédfüggvény az egységes térközökhöz. Miután elkészített két-három blokkot, a továbbiak hozzáadása már rutinfeladat.
További oldalak hozzáadása
Ahogy bővül a könyvtára, állítson össze különböző oldalakat ugyanazokból a blokkokból:
<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>
Ugyanazok a blokkok több oldalt is kiszolgálnak, mindegyiket eltérő alapértékekkel. Ez a könyvtáras megközelítés előnye: építse meg egyszer a blokkokat, és állítsa össze belőlük annyi oldalt, amennyire szüksége van.
Következő lépések
- Attribútumok regisztrálása: teljes referencia a mezőtípusokról és tulajdonságokról
- Mezőtípusok: az összes elérhető mezőtípus
- Mezőminták receptgyűjteménye: feltételes csoportok, intelligens választók és ismétlőreceptek
- Pages: sablonzárolás, szerkesztési módok és kulcs szerinti összevonás
- Fájlalapú oldalak építése: gyakorlati útmutató az oldalsablonokról és szinkronizálásról
- Interaktivitás: kliensoldali viselkedés hozzáadása a blokkokhoz