Pereiti prie turinio

Blokų bibliotekos kūrimas

Blokų biblioteka – tai savarankiškų sekcijų blokų rinkinys, iš kurių komponuojami ištisi puslapiai. Kiekvienas blokas turi savo schemą, šabloną ir stilius. Blockstudio suteikia karkasą: Tailwind CSS apdorojimą, atributų registravimą ir puslapių sinchronizavimą. Blokus kuriate jūs.

Šiame vadove parodoma, kaip sukurti biblioteką nuo pradžių, laikantis tos pačios architektūros, kuri naudojama šimtuose gamybinių temų. Pabaigoje turėsite veikiančią temą su pagrindine sekcija, funkcijų tinkleliu ir sudėtu pagrindiniu puslapiu.

Aplankų struktūra

Kiekviena Blockstudio tema turi tą pačią struktūrą:

Kodas
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

Blokai laikomi blockstudio/sections/. Kiekvienas blokas yra aplankas su block.json schema ir index.php šablonu. Puslapiai laikomi pages/ ir komponuoja blokus naudodami sintaksę <block>.

Pagrindiniai failai

blockstudio.json

Šis failas nurodo, kaip Blockstudio apdoroja jūsų temą. Visose temose konfigūracija vienoda:

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 pašalina numatytuosius WordPress blokų stilius. fullWidth nustato, kad page įrašų tipai užimtų visą plotį. canvas įjungia redaktoriaus drobės režimą, kad redaguoti būtų paprasčiau.

Laukas tailwind.config sąmoningai paliktas tuščias. Naudojant Tailwind v4, visa konfigūracija laikoma style.css, laikantis principo „pirmiausia CSS“.

index.php

Pagrindinis WordPress šablonas. Tai standartinis WordPress, niekaip nesusijęs su 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>

Jei reikia naršymo, pridėkite header.php ir footer.php. Kol kas blokams atvaizduoti pakanka minimalaus šablono.

Dizaino žetonai

Visi temos stiliai nustatomi faile style.css, naudojant Tailwind v4 direktyvą @theme. Tai jūsų dizaino sistemos pagrindas.

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

Kiekvienai temai reikia bent šių elementų:

Žetonas Paskirtis
--font-sans arba --font-serif Pagrindinis šriftas
--color-bg Puslapio fonas
--color-elevated Kortelės / paviršiaus fonas
--color-subtle Kraštinės, skirtukai
--color-muted Antrinis tekstas
--color-accent Pagrindinė prekės ženklo spalva

Šie žetonai automatiškai sukuria Tailwind paslaugų klases. --color-accent tampa bg-accent, text-accent, border-accent ir t. t.

Šviesiai temai pakeiskite reikšmes:

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

Baziniai stiliai ir paslaugų klasės

Po bloko @theme pridėkite turinio srities stilius, bazinio sluoksnio numatytąsias reikšmes ir pasirinktines paslaugų klases.

Turinio srities stiliai turi būti už @layer ribų, kad juos perimtų WordPress redaktorius:

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

Bazinis sluoksnis elementų numatytosioms reikšmėms:

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

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

	p {
		text-wrap: pretty;
	}
}

Pasirinktinės paslaugų klasės daugkartinio naudojimo šablonams. Kiekvienoje temoje apibrėžiama container klasė, kad sekcijų tarpai būtų vienodi, o paprastai taip pat ir card, badge bei mygtukų klasės:

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

Pseudoatrankos turi būti bloke @utility ir naudoti CSS įdėtinę sintaksę (&:hover). Niekada neįtraukite jų į paslaugų klasės pavadinimą. @utility btn-primary:hover {} yra netinkamas ir Tailwind jį atmes.

@source įterptinis

Blockstudio automatiškai ieško Tailwind klasių jūsų blokų šablonuose. Tačiau išorėje blokų šablonų naudojamos klasės (functions.php, header.php, index.php) nėra tikrinamos. Deklaruokite jas naudodami @source inline:

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

Taip nurodoma Tailwind įtraukti šias klases į išvestį, nors jos yra tik PHP failuose, kurie netikrinami.

Sekcijos šablonas

Sekcijos šablonas yra svarbiausia Blockstudio blokų bibliotekos taisyklė. Jis užtikrina vienodus tarpus, fono perjungimą ir užpildo valdymą visuose blokuose, naudojant du bendrus mechanizmus: pasirinktinį lauką ir pagalbinę PHP funkciją.

Sekcijos laukas

Sukurkite bendrą lauko apibrėžtį, kurią galėtų naudoti kiekvienas blokas:

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

Šis laukas rodomas kiekvieno bloko tikrintuve, skirtuke „Sekcija“. Klientai gali valdyti dvi parinktis: įjungti akcento foną ir pašalinti apatinį užpildą (naudinga kraunant sekcijas vieną virš kitos be tarpų).

Sekcijos pagalbinė funkcija

Faile functions.php sukurkite pagalbinę funkciją, kuri šiuos atributus paverčia CSS klasėmis:

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

Kiekvieno bloko šablonas šią pagalbinę funkciją iškviečia pirmoje eilutėje. Ji grąžina dvi klasių eilutes: vieną išoriniam <section> elementui, kitą vidiniam <div> konteineriui.

Tailwind konfigūracijos filtras

Taip pat faile functions.php pridėkite filtrą, kuris perduoda jūsų style.css Blockstudio Tailwind procesoriui:

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

Taip nurodoma Blockstudio naudoti jūsų style.css kaip Tailwind v4 konfigūracijos šaltinį. Be šio filtro jūsų @theme žetonai ir @utility apibrėžtys nebūtų pasiekiami blokų šablonuose.

Pirmasis blokas: pagrindinė sekcija

Pagrindinė sekcija parodo visą bloko kūrimo šabloną. Pradėkite nuo schemos:

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

Svarbūs šablono elementai:

Apvalkalas tabs sukuria dviejų skirtukų tikrintuvą: „Turinys“ skirtas bloko laukams, o „Sekcija“ – bendriems sekcijos valdikliams. Tokią struktūrą naudoja kiekvienas blokas.

Laukai suskirstyti į group konteinerius. Grupės vizualiai atskiria susijusius laukus tikrintuve. Pirmoje grupėje yra teksto laukai, antroje – nuorodų laukai.

Numatytosios reikšmės suteikia prasmingą turinį, kad įterptas blokas iškart atrodytų užbaigtas. Tai ypač svarbu komponuojant puslapį, nes blokai pridedami be naudotojo įsikišimo.

Dabar sukurkite šabloną:

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>

Šablone naudojamas nuoseklus šablonas:

  1. Iškvieskite sekcijos pagalbinę funkciją, kad gautumėte CSS klases
  2. Išorinis <section> su useBlockProps ir sekcijos klasėmis
  3. Vidinis <div> su konteinerio klasėmis
  4. Atvaizduokite turinį iš $a (sutrumpinta atributų forma)
  5. Pasirinktinai atvaizduokite laukus
  6. Tinkamai apsaugokite išvestį: tekstui naudokite esc_html(), URL adresams – esc_url(), atributams – esc_attr()

Kartotuvų pridėjimas: funkcijų tinklelis

Kartotuvai leidžia klientams pridėti, pašalinti ir pertvarkyti elementus. Klasikinis pavyzdys – funkcijų tinklelis:

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

Savybė textMinimized nurodo, koks tekstas rodomas sutraukus kartotuvo eilutę. Ji nuskaito lauko title reikšmę, o jei jis tuščias, rodo „Funkcija“. Taip tikrintuvu patogu naudotis net tada, kai turite daug elementų.

Masyve default pateikiami pradiniai elementai. Jie atsiranda pirmą kartą įterpus bloką. Visada nurodykite tikroviškas numatytąsias reikšmes, kad blokas iškart atrodytų užbaigtas.

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>

Kartotuvo elementai pasiekiami kaip paprastas PHP masyvas. Cikluokite naudodami foreach, o kiekvieno elemento laukus pasiekite pagal jų id.

Vaizdai ir vietos rezervavimo elementai

Blokams su vaizdais naudokite lauko tipą files ir komponentą MediaPlaceholder. Vietos rezervavimo elementas redaktoriuje rodo vilkimo ir numetimo sritį:

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

Šablone atvaizduokite vaizdą naudodami wp_get_attachment_image(), o jei vaizdas nepasirinktas, rodykite vietos rezervavimo SVG:

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() grąžina įterptinį SVG, kuriame naudojama currentColor su kintamuoju --color-accent, todėl jis automatiškai prisitaiko prie jūsų temos. Šviesioms temoms naudokite blockstudio_placeholder_light(). Abiem galima perduoti varianto argumentą:

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

Puslapių komponavimas

Puslapiai komponuojami iš blokų, sudarančių visą išdėstymą, naudojant sintaksę <block>. Sukurkite pagrindinį puslapį:

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>

Štai ir viskas. Kiekvienas <block> elementas įterpia bloką su numatytosiomis atributų reikšmėmis. Paleiskite wp bs pages sync, kad pritaikytumėte puslapio šaltinį WordPress.

Norėdami konkrečiame puslapyje pakeisti numatytąsias reikšmes, tiesiogiai perduokite atributus:

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

Kai templateLock nustatyta į "all", klientai negali pridėti, pašalinti ar pertvarkyti blokų. Puslapio struktūra užfiksuota jūsų šablone. Kitus užrakinimo režimus ir redagavimo valdiklius rasite Puslapių dokumentacijoje.

Bibliotekos plėtra

Minimali biblioteka prasideda nuo 3–5 blokų. Išsamią biblioteką sudaro 8–14 blokų. Toliau pateikiami įprasti blokų tipai, apytiksliai surikiuoti pagal jų naudojimo dažnumą:

Blokas Aprašymas Pagrindiniai laukai
Pagrindinė sekcija Didelė antraštė su raginimo veikti mygtukais antraštė, aprašymas, nuorodos
Funkcijos Privalumų tinklelis antraštė, kartotuvas su pavadinimu + aprašymu
Raginimas veikti Raginimo veikti juosta antraštė, aprašymas, nuoroda
Kainodara Planų palyginimas antraštė, kartotuvas su pavadinimu + kaina + funkcijomis
Atsiliepimai Klientų citatos kartotuvas su citata + vardu + pareigomis
DUK Išskleidžiami klausimai antraštė, kartotuvas su klausimu + atsakymu
Logotipai Klientų logotipų rinkinys antraštė (logotipai paprastai įrašomi tiesiogiai SVG formatu)
Turinys Kintančios teksto + vaizdo eilutės kartotuvas su antrašte + aprašymu + vaizdu
Galerija Viso pločio vaizdas su antrašte antraštė, aprašymas, vaizdas
Komanda Komandos narių tinklelis antraštė, kartotuvas su vardu + pareigomis + vaizdu
Statistika Pagrindiniai rodikliai kartotuvas su skaičiumi + etikete

Kiekvienas blokas kuriamas pagal tą patį šabloną: skirtukai („Turinys“ ir „Sekcija“), grupės tvarkai palaikyti, kartotuvai sąrašams ir sekcijos pagalbinė funkcija vienodiems tarpams. Sukūrus du ar tris blokus, kitus pridėti bus paprasta.

Daugiau puslapių

Augant bibliotekai, iš tų pačių blokų komponuokite skirtingus puslapius:

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>

Tie patys blokai tinka keliems puslapiams, kurių kiekvienas turi skirtingas numatytąsias reikšmes. Toks ir yra bibliotekos principas: sukurkite blokus vieną kartą ir komponuokite iš jų tiek puslapių, kiek reikia.

Tolesni žingsniai