Treci la conținut

Crearea unei biblioteci de blocuri

O bibliotecă de blocuri este un set de blocuri de secțiune autonome, care se combină pentru a alcătui pagini complete. Fiecare bloc își gestionează schema, șablonul și stilurile. Blockstudio oferă cadrul: procesarea Tailwind CSS, înregistrarea atributelor și sincronizarea paginilor. Blocurile vă aparțin.

Acest ghid vă arată cum să construiți o bibliotecă de la zero, urmând aceeași arhitectură folosită în sute de teme de producție. La final, veți avea o temă funcțională cu o secțiune principală, o grilă de caracteristici și o pagină de pornire compusă.

Structura folderelor

Fiecare temă Blockstudio urmează același aranjament:

Cod
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

Blocurile se află în blockstudio/sections/. Fiecare bloc este un dosar cu o schemă block.json și un șablon index.php. Paginile se află în pages/ și compun blocuri folosind sintaxa <block>.

Fișiere de bază

blockstudio.json

Acest fișier configurează modul în care Blockstudio vă procesează tema. Configurația este aceeași pentru fiecare temă:

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 elimină stilurile implicite ale blocurilor WordPress. fullWidth face ca tipurile de conținut page să ocupe toată lățimea. canvas activează modul pânză al editorului, pentru o experiență de editare mai simplă.

Câmpul tailwind.config este lăsat intenționat gol. Cu Tailwind v4, toată configurația se află în style.css, urmând abordarea bazată mai întâi pe CSS.

index.php

Șablonul principal WordPress. Acesta este WordPress obișnuit, fără nimic specific pentru 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>

Adăugați un header.php și un footer.php când aveți nevoie de navigare. Deocamdată, un șablon minimal este suficient pentru a randa blocuri.

Tokenuri de design

Toată tematizarea se face în style.css folosind directiva @theme din Tailwind v4. Acesta este nucleul sistemului de design.

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;
}

Fiecare temă are nevoie cel puțin de:

Token Scop
--font-sans sau --font-serif Font principal
--color-bg Fundalul paginii
--color-elevated Fundalul cardului/suprafeței
--color-subtle Borduri, separatoare
--color-muted Text secundar
--color-accent Culoarea principală a mărcii

Aceste tokenuri generează automat utilitare Tailwind. --color-accent devine bg-accent, text-accent, border-accent și așa mai departe.

Pentru o temă deschisă, inversați valorile:

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;
}

Stiluri de bază și utilitare

Sub blocul @theme, adăugați stilurile pentru corpul paginii, valorile implicite ale stratului de bază și utilitarele personalizate.

Stilurile pentru corpul paginii trebuie să fie în afara blocului @layer, ca să le preia editorul WordPress:

CSS
body {
	@apply bg-bg font-sans text-white antialiased;
}

Stratul de bază pentru valorile implicite ale elementelor:

CSS
@layer base {
	section {
		@apply relative overflow-hidden;
	}

	h1, h2, h3 {
		text-wrap: balance;
	}

	p {
		text-wrap: pretty;
	}
}

Utilitare personalizate pentru modele reutilizabile. Fiecare temă definește un utilitar container pentru spațiere consecventă între secțiuni și, de obicei, utilitarele card, badge și pentru butoane:

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);
	}
}

Selectorii pseudo se scriu în interiorul blocului @utility, folosind imbricarea CSS (&:hover). Nu îi includeți niciodată în numele utilitarului. @utility btn-primary:hover {} este invalid și va fi respins de Tailwind.

@source inline

Blockstudio scanează automat șabloanele blocurilor pentru clase Tailwind. Însă clasele folosite în afara șabloanelor blocurilor (în functions.php, header.php, index.php) nu sunt scanate. Declarați-le cu @source inline:

CSS
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");

Astfel, Tailwind va include aceste clase în rezultat, deși ele apar doar în fișierele PHP care nu sunt scanate.

Modelul secțiunii

Modelul secțiunii este cea mai importantă convenție dintr-o bibliotecă de blocuri Blockstudio. Acesta oferă tuturor blocurilor spațiere consecventă, alternarea fundalului și controlul spațierii interioare prin două mecanisme comune: un câmp personalizat și un ajutor PHP.

Câmpul secțiunii

Creați o definiție de câmp comună la care să se poată face referire din fiecare bloc:

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"
				}
			]
		}
	]
}

Acest câmp apare în inspectorul fiecărui bloc, sub o filă „Secțiune”. Clienții au două controale: activarea unui fundal de accent și eliminarea spațierii interioare de jos (utilă pentru suprapunerea secțiunilor fără spații între ele).

Ajutorul pentru secțiune

În functions.php, creați un ajutor care transformă aceste atribute în clase 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 );
}

Șablonul fiecărui bloc apelează acest ajutor chiar pe primul rând. Ajutorul returnează două șiruri de clase: unul pentru elementul exterior <section> și unul pentru containerul interior <div>.

Filtrul de configurare Tailwind

Tot în functions.php, adăugați filtrul care transmite configurația style.css către procesorul Tailwind din 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 '';
	}
);

Astfel, Blockstudio va folosi style.css drept sursă de configurare Tailwind v4. Fără aceasta, tokenurile @theme și definițiile @utility nu ar fi disponibile în șabloanele blocurilor.

Primul bloc: secțiunea principală

O secțiune principală demonstrează modelul complet al blocului. Începeți cu schema:

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" }
						]
					}
				]
			}
		]
	}
}

Modele importante de observat:

Elementul de încadrare tabs creează un inspector cu două file: „Conținut” pentru câmpurile blocului și „Secțiune” pentru controalele comune ale secțiunii. Fiecare bloc folosește această structură.

Câmpurile sunt organizate în containere group. Grupurile separă vizual câmpurile asociate în inspector. Primul grup conține câmpurile text, al doilea pe cele pentru linkuri.

Valorile implicite oferă conținut util, astfel încât blocul să arate complet imediat după inserare. Acest lucru este esențial pentru compunerea paginilor, unde blocurile sunt adăugate fără interacțiunea utilizatorului.

Acum, șablonul:

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>

Șablonul urmează un model consecvent:

  1. Apelați ajutorul pentru secțiune pentru a obține clasele CSS
  2. Elementul exterior <section> cu useBlockProps și clasele secțiunii
  3. Elementul interior <div> cu clasele containerului
  4. Conținut randat din $a (prescurtarea atributelor)
  5. Randare condiționată pentru câmpurile opționale
  6. Escapare corectă: esc_html() pentru text, esc_url() pentru URL-uri, esc_attr() pentru atribute

Adăugarea câmpurilor repetabile: grila de caracteristici

Câmpurile repetabile le permit clienților să adauge, să elimine și să reordoneze elemente. Grila de caracteristici este un exemplu clasic:

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" }
						]
					}
				]
			}
		]
	}
}

Proprietatea textMinimized controlează textul afișat când un rând al câmpului repetabil este restrâns. Aceasta citește valoarea câmpului title și, dacă acesta este gol, folosește „Caracteristică”. Astfel, inspectorul rămâne ușor de folosit când aveți multe elemente.

Matricea default furnizează elementele inițiale. Acestea apar la prima inserare a blocului. Furnizați întotdeauna valori implicite realiste, astfel încât blocul să arate complet imediat.

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>

Elementele câmpului repetabil sunt accesate ca o matrice simplă PHP. Parcurgeți-le cu foreach și accesați câmpurile fiecărui element prin id.

Imagini și substituenți

Pentru blocurile cu imagini, folosiți tipul de câmp files și componenta MediaPlaceholder. Substituentul afișează în editor o zonă pentru glisare și fixare:

JSON
{
	"id": "image",
	"type": "files",
	"label": "Image"
}

În șablon, randați imaginea cu wp_get_attachment_image() și afișați un SVG substituent când nu este selectată nicio imagine:

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() returnează un SVG în linie care folosește currentColor cu variabila --color-accent, astfel încât se adaptează automat la tema dvs. Pentru temele deschise, folosiți blockstudio_placeholder_light(). Ambele acceptă un argument variantă:

PHP
blockstudio_placeholder_dark( 'dashboard' )  // Dashboard mockup
blockstudio_placeholder_dark( 'chart' )      // Chart illustration
blockstudio_placeholder_dark( 'product' )    // Product shot

Compunerea paginilor

Paginile compun blocuri în structuri complete folosind sintaxa <block>. Creați o pagină de pornire:

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>

Gata. Fiecare element <block> inserează blocul cu valorile implicite ale atributelor. Rulați wp bs pages sync pentru a aplica sursa paginii în WordPress.

Pentru a suprascrie valorile implicite pe o anumită pagină, transmiteți direct atributele:

PHP
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>

Cu templateLock setat la "all", clienții nu pot adăuga, elimina sau rearanja blocuri. Structura paginii este blocată în șablonul dvs. Consultați Pagini pentru alte moduri de blocare și controale de editare.

Dezvoltarea la scară

O bibliotecă minimală începe cu 3-5 blocuri. O bibliotecă cuprinzătoare are 8-14. Iată tipurile obișnuite de blocuri, aproximativ în ordinea frecvenței de apariție:

Bloc Descriere Câmpuri principale
Secțiune principală Titlu mare cu CTA-uri titlu, descriere, linkuri
Caracteristici Grilă de beneficii titlu, câmp repetabil cu titlu + descriere
CTA Banner cu îndemn la acțiune titlu, descriere, link
Prețuri Compararea planurilor titlu, câmp repetabil cu nume + preț + caracteristici
Testimoniale Citate ale clienților câmp repetabil cu citat + nume + rol
Întrebări frecvente Acordeon cu întrebări titlu, câmp repetabil cu întrebare + răspuns
Logouri Colaj cu logourile clienților titlu (de regulă, logourile sunt SVG-uri hardcodate)
Conținut Rânduri alternative cu text + imagine câmp repetabil cu titlu + descriere + imagine
Prezentare Imagine pe toată lățimea, cu legendă titlu, descriere, imagine
Echipă Grilă cu membri echipei titlu, câmp repetabil cu nume + rol + imagine
Statistici Indicatori principali câmp repetabil cu număr + etichetă

Fiecare bloc urmează același model: file (Conținut + Secțiune), grupuri pentru organizare, câmpuri repetabile pentru liste și ajutorul pentru secțiune pentru spațiere consecventă. După ce construiți două sau trei blocuri, adăugarea altora devine mecanică.

Adăugarea altor pagini

Pe măsură ce biblioteca dvs. se extinde, compuneți pagini diferite din aceleași blocuri:

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>

Aceleași blocuri pot fi folosite pe mai multe pagini, fiecare cu valori implicite diferite. Acesta este avantajul abordării bazate pe bibliotecă: construiți blocurile o singură dată și combinați-le în oricâte pagini aveți nevoie.

Pașii următori