Preskoči na vsebino

Izdelava knjižnice blokov

Knjižnica blokov je nabor samostojnih blokov razdelkov, ki jih je mogoče sestaviti v celotne strani. Vsak blok ima lastno shemo, predlogo in sloge. Blockstudio zagotavlja ogrodje: obdelavo Tailwind CSS, registracijo atributov in sinhronizacijo strani. Bloke zagotovite sami.

Ta vodnik vas popelje skozi izdelavo knjižnice od začetka, po enaki arhitekturi, kot jo uporablja na stotine produkcijskih tem. Na koncu boste imeli delujočo temo z uvodnim razdelkom, mrežo funkcij in sestavljeno domačo stranjo.

Struktura map

Vsaka tema Blockstudio ima enako postavitev:

Koda
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 so v blockstudio/sections/. Vsak blok je mapa s shemo block.json in predlogo index.php. Strani so v pages/ in sestavljajo bloke z uporabo sintakse <block>.

Temeljne datoteke

blockstudio.json

Ta datoteka določa, kako Blockstudio obdeluje vašo temo. Konfiguracija je enaka za vsako temo:

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 odstrani privzete sloge blokov WordPress. fullWidth poskrbi, da se vrste objav page raztegnejo čez celotno širino. canvas omogoči način platna urejevalnika za preglednejše urejanje.

Polje tailwind.config je namenoma prazno. Z Tailwind v4 je vsa konfiguracija v style.css po pristopu, ki daje prednost CSS.

index.php

Glavna predloga WordPress. To je standardni WordPress, nič posebnega za 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>

Po potrebi dodajte header.php in footer.php za navigacijo. Za zdaj za upodabljanje blokov zadostuje preprosta predloga.

Oblikovni žetoni

Vse oblikovanje teme poteka v style.css z direktivo Tailwind v4 @theme. To je jedro vašega oblikovnega sistema.

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

Vsaka tema potrebuje vsaj:

Žeton Namen
--font-sans ali --font-serif Primarna pisava
--color-bg Ozadje strani
--color-elevated Ozadje kartice/površine
--color-subtle Obrobe, ločila
--color-muted Sekundarno besedilo
--color-accent Primarna barva znamke

Ti žetoni samodejno ustvarijo pripomočke Tailwind. --color-accent postane bg-accent, text-accent, border-accent itd.

Pri svetli temi obrnite vrednosti:

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

Osnovni slogi in pripomočki

Pod blokom @theme dodajte sloge telesa strani, privzete vrednosti osnovne plasti in pripomočke po meri.

Slogi telesa strani morajo biti zunaj bloka @layer, da jih urejevalnik WordPress zazna:

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

Osnovna plast za privzete vrednosti elementov:

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

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

	p {
		text-wrap: pretty;
	}
}

Pripomočki po meri za vzorce, ki jih je mogoče znova uporabiti. Vsaka tema določa pripomoček container za dosledne razmike med razdelki, običajno pa tudi pripomočke card, badge in za gumbe:

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

Psevdoselektorji sodijo v blok @utility, kjer uporabijo gnezdenje CSS (&:hover). Nikoli jih ne vključite v ime pripomočka. @utility btn-primary:hover {} je neveljaven in ga bo Tailwind zavrnil.

@source v vrstici

Blockstudio samodejno pregleda predloge vaših blokov in poišče razrede Tailwind. Vendar razredov, uporabljenih zunaj predlog blokov (v functions.php, header.php, index.php), ne pregleda. Navedite jih z @source inline:

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

S tem določite, naj Tailwind vključi te razrede v izhod, čeprav so samo v datotekah PHP, ki niso pregledane.

Vzorec razdelka

Vzorec razdelka je najpomembnejši dogovor v knjižnici blokov Blockstudio. Vsakemu bloku zagotavlja enotne razmike, preklapljanje ozadja in nadzor odmikov z dvema skupnima mehanizmoma: poljem po meri in pomočnikom PHP.

Polje razdelka

Ustvarite skupno definicijo polja, na katero se lahko sklicuje vsak blok:

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

To polje se prikaže v nadzorni plošči vsakega bloka pod zavihkom »Section«. Uporabniki dobijo dva kontrolnika: preklop poudarjenega ozadja in odstranitev spodnjega odmika (uporabno za zlaganje razdelkov brez vrzeli).

Pomočnik za razdelek

V functions.php ustvarite pomočnika, ki te atribute pretvori v razrede 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 );
}

Vsaka predloga bloka tega pomočnika pokliče v prvi vrstici. Pomočnik vrne dva niza razredov: enega za zunanji element <section> in drugega za notranji vsebnik <div>.

Filter konfiguracije Tailwind

Tudi v functions.php dodajte filter, ki vaš style.css posreduje procesorju Tailwind za 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 '';
	}
);

S tem določite, naj Blockstudio uporabi vaš style.css kot vir konfiguracije Tailwind v4. Brez tega žetoni @theme in definicije @utility ne bi bili na voljo v predlogah blokov.

Vaš prvi blok: uvodni razdelek

Uvodni razdelek prikazuje celoten vzorec bloka. Začnite s shemo:

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

Pomembni vzorci:

Ovoj tabs ustvari nadzorno ploščo z dvema zavihkoma: »Content« za polja bloka in »Section« za skupne kontrolnike razdelka. To strukturo uporablja vsak blok.

Polja so urejena v vsebnike group. Skupine v nadzorni plošči vizualno ločijo povezana polja. Prva skupina vsebuje besedilna polja, druga pa polja povezav.

Privzete vrednosti zagotovijo smiselno vsebino, zato je blok videti dokončan takoj po vstavitvi. To je ključno pri sestavljanju strani, kjer se bloki dodajo brez posredovanja uporabnika.

Zdaj še predloga:

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>

Predloga sledi enotnemu vzorcu:

  1. Pokličite pomočnika za razdelek, da pridobite razrede CSS
  2. Zunanji <section> z useBlockProps in razredi razdelka
  3. Notranji <div> z razredi vsebnika
  4. Upodobite vsebino iz $a (okrajšava za atribute)
  5. Pogojno upodabljanje izbirnih polj
  6. Pravilno ubežanje: esc_html() za besedilo, esc_url() za URL-je, esc_attr() za atribute

Dodajanje ponavljalnikov: mreža funkcij

Ponavljalniki uporabnikom omogočajo dodajanje, odstranjevanje in spreminjanje vrstnega reda elementov. Mreža funkcij je klasičen primer:

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

Lastnost textMinimized določa besedilo, prikazano, ko je vrstica ponavljalnika strnjena. Prebere vrednost polja title, če je prazno, pa uporabi »Feature«. Tako je nadzorna plošča uporabna tudi pri velikem številu elementov.

Polje default določa začetne elemente. Prikažejo se ob prvi vstavitvi bloka. Vedno nastavite realistične privzete vrednosti, da bo blok takoj videti dokončan.

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>

Do elementov ponavljalnika dostopate kot do navadnega polja PHP. Ponavljajte z foreach, do polj posameznega elementa pa dostopajte prek njihovih id.

Slike in nadomestna mesta

Za bloke s slikami uporabite vrsto polja files in komponento MediaPlaceholder. Nadomestno mesto v urejevalniku prikaže območje za povleci in spusti:

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

V predlogi upodobite sliko z wp_get_attachment_image(), kadar ni izbrana nobena slika, pa prikažite nadomestni 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() vrne vdelani SVG, ki uporablja currentColor s spremenljivko --color-accent, zato se samodejno prilagodi vaši temi. Pri svetlih temah uporabite blockstudio_placeholder_light(). Oba sprejemata argument različice:

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

Sestavljanje strani

Strani sestavljajo bloke v celotne postavitve s sintakso <block>. Ustvarite domačo stran:

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>

To je vse. Vsak element <block> vstavi blok s privzetimi vrednostmi atributov. Za uporabo vira strani v WordPress zaženite wp bs pages sync.

Če želite za določeno stran preglasiti privzete vrednosti, atribute podajte neposredno:

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

Ko je templateLock nastavljen na "all", uporabniki ne morejo dodajati, odstranjevati ali preurejati blokov. Struktura strani je zaklenjena v predlogi. Za druge načine zaklepanja in kontrolnike urejanja glejte Strani.

Povečevanje obsega

Preprosta knjižnica se začne s 3–5 bloki. Obsežna knjižnica jih ima 8–14. Tukaj so pogoste vrste blokov, približno po pogostosti pojavljanja:

Blok Opis Ključna polja
Uvodni razdelek Velik naslov s pozivi k dejanju heading, description, links
Funkcije Mreža prednosti heading, repeater with title + description
Poziv k dejanju Pasica s pozivom k dejanju heading, description, link
Cenik Primerjava paketov heading, repeater with name + price + features
Pričevanja Izjave strank repeater with quote + name + role
Pogosta vprašanja Harmonika z vprašanji heading, repeater with question + answer
Logotipi Množica logotipov strank heading (logotipi so običajno vnaprej zapisani SVG-ji)
Vsebina Izmenjujoče se vrstice besedila in slik repeater with heading + description + image
Predstavitev Slika čez celotno širino z napisom heading, description, image
Ekipa Mreža članov ekipe heading, repeater with name + role + image
Statistika Ključne metrike repeater with number + label

Vsak blok sledi istemu vzorcu: zavihki (Content + Section), skupine za organizacijo, ponavljalniki za sezname in pomočnik za razdelek za enotne razmike. Ko izdelate dva ali tri bloke, je dodajanje novih rutinsko opravilo.

Dodajanje strani

Ko se vaša knjižnica veča, iz istih blokov sestavljajte različne strani:

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>

Isti bloki se uporabljajo na več straneh, vsaka z različnimi privzetimi vrednostmi. To je prednost pristopa s knjižnico: bloke izdelate enkrat in jih sestavite v toliko strani, kot jih potrebujete.

Naslednji koraki