Block Theme z theme.json: Templates, Parts i Child Theme

Motyw blokowy określa wygląd witryny WordPress. Szablony opisują całe strony. Części szablonu to powtarzalne fragmenty, na przykład nagłówek i stopka. Plik theme.json określa kolory, czcionki i inne ustawienia wyglądu.

Przykład przedstawia mały motyw, a następnie motyw potomny, czyli rozszerzenie przechowujące zmiany w osobnym katalogu. Wyjaśnia trzy kwestie: wybór szablonu, miejsce zapisu zmian z edytora witryny oraz ustawienia dziedziczone przez motyw potomny. Opis dotyczy WordPressa 7.1. Historyczne testy przeprowadzono 30 września 2026 w wersji 7.1.2.

Wymagane pliki

Samodzielny motyw blokowy wymaga plików style.css i templates/index.html. Pierwszy zawiera co najmniej nazwę motywu. Drugi jest szablonem zastępczym, używanym przy braku bardziej odpowiedniego szablonu. Plik theme.json nie jest wymagany do rozpoznania motywu, ale ułatwia określanie wyglądu. Ten przykład dodaje także singular.html, aby pojedyncze wpisy i strony wyświetlały pełną treść.

lw-base/
├── style.css
├── theme.json
├── templates/
│   ├── index.html
│   └── singular.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
│   └── footer-credits.php
└── styles/
    └── night.json

Komentarz na początku style.css opisuje motyw. Dodatkowe dane są istotne między innymi przy publikacji w katalogu motywów WordPress. W tym przykładzie plik nie wymaga własnych reguł CSS, ponieważ wygląd określa theme.json. Wpis Requires at least: 6.6 podaje minimalną wersję potrzebną do użycia formatu JSON w wersji 3.

/*
Theme Name: LW Base
Theme URI: https://example.com/lw-base
Author: Lukas Wojcik
Author URI: https://lukaswojcik.com
Description: Minimal block theme with templates, template parts, a pattern and a style variation.
Version: 1.0.0
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: lw-base
*/

Katalogi mają określone zadania: templates/ zawiera szablony całych stron, parts/ powtarzalne części, patterns/ gotowe grupy bloków, a styles/ alternatywne warianty wyglądu. Starsze nazwy block-templates/ i block-template-parts/ nadal działają w starszych motywach.

Kolory i czcionki w theme.json

settings określa kolory, rozmiary czcionek i narzędzia dostępne w edytorze. styles stosuje konkretne wartości. Przykład udostępnia trzy kolory i używa base jako tła. slug to krótka nazwa techniczna elementu, na przykład accent dla koloru akcentu.

Format w wersji 3 jest dostępny od WordPressa 6.6. Ustawienie defaultFontSizes ma wartość false, aby własne rozmiary mogły korzystać ze standardowych nazw small, medium i large. Podobną rolę dla rozmiarów odstępów pełni defaultSpacingSizes. Starsze wersje formatu JSON pozostają obsługiwane.

$schema wskazuje opis dozwolonych właściwości. Edytory kodu mogą dzięki temu sygnalizować błędy i uzupełniać wpisy. Odnośnik dla WordPressa 7.1 odpowiada omawianej wersji. Odnośnik zawierający trunk śledzi natomiast bieżący rozwój i może obejmować nowsze funkcje.

{
	"$schema": "https://schemas.wp.org/wp/7.1/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"layout": {
			"contentSize": "720px",
			"wideSize": "1200px"
		},
		"color": {
			"defaultPalette": false,
			"palette": [
				{ "slug": "base", "color": "#ffffff", "name": "Base" },
				{ "slug": "contrast", "color": "#111827", "name": "Contrast" },
				{ "slug": "accent", "color": "#0369a1", "name": "Accent" }
			]
		},
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{ "slug": "small", "size": "0.875rem", "name": "Small" },
				{ "slug": "medium", "size": "1rem", "name": "Medium" },
				{ "slug": "large", "size": "1.5rem", "name": "Large" }
			],
			"fontFamilies": [
				{
					"slug": "system",
					"name": "System",
					"fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif"
				}
			]
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--base)",
			"text": "var(--wp--preset--color--contrast)"
		},
		"typography": {
			"fontFamily": "var(--wp--preset--font-family--system)",
			"fontSize": "var(--wp--preset--font-size--medium)",
			"lineHeight": "1.6"
		},
		"spacing": {
			"padding": { "top": "1.5rem", "right": "1.5rem", "bottom": "1.5rem", "left": "1.5rem" }
		},
		"elements": {
			"link": {
				"color": { "text": "var(--wp--preset--color--accent)" }
			}
		}
	},
	"templateParts": [
		{ "name": "header", "title": "Header", "area": "header" },
		{ "name": "footer", "title": "Footer", "area": "footer" }
	]
}

templateParts przypisuje nagłówkowi i stopce nazwę oraz obszar. WordPress udostępnia header, footer i uncategorized, a od wersji 7.0 także navigation-overlay. Bez własnego tagName obszar określa również otaczający element HTML.

Listy i pełna treść wpisów

Poniższy templates/index.html wyświetla tytuły i zajawki. Blok pętli zapytania, Query Loop, powtarza ten układ dla znalezionych wpisów. Dzięki "inherit":true blok przejmuje wybór wpisów dla bieżącej strony, na przykład wyników wyszukiwania lub wybranej kategorii.

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:query {"queryId":1,"query":{"perPage":10,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","inherit":true}} -->
	<div class="wp-block-query">
		<!-- wp:post-template -->
			<!-- wp:post-title {"isLink":true} /-->
			<!-- wp:post-excerpt /-->
		<!-- /wp:post-template -->

		<!-- wp:query-pagination -->
			<!-- wp:query-pagination-previous /-->
			<!-- wp:query-pagination-numbers /-->
			<!-- wp:query-pagination-next /-->
		<!-- /wp:query-pagination -->
	</div>
	<!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Dla pojedynczych wpisów i stron plik templates/singular.html dodaje blok post-content. Ten blok wyświetla pełną treść. Bez dodatkowego szablonu powyższy szablon zastępczy pokazywałby także tutaj tylko tytuł i zajawkę. Komentarze, osobna strona błędu i dalsze elementy wyglądu wykraczają poza ten mały przykład startowy.

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
<!-- wp:post-title {"level":1} /-->
<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Części szablonu są dołączane pod nazwami header i footer. Atrybut theme został celowo pominięty, dzięki czemu WordPress szuka w aktywnym motywie. Wpisanie na stałe "theme":"lw-base" uniemożliwia zwykłe wyświetlenie tej części przy aktywnym motywie potomnym. Przy włączonym wyświetlaniu informacji diagnostycznych może zamiast tego pojawić się komunikat błędu.

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
	<!-- wp:site-title /-->
	<!-- wp:navigation /-->
</div>
<!-- /wp:group -->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
	<!-- wp:pattern {"slug":"lw-base/footer-credits"} /-->
</div>
<!-- /wp:group -->

Stopka wczytuje wzorzec, czyli gotową grupę bloków. WordPress automatycznie rejestruje pliki PHP w patterns/, gdy nagłówek zawiera Title i Slug. Funkcja esc_html_e() pozwala tu tłumaczyć widoczny tekst przez domenę tekstową lw-base, czyli identyfikator tłumaczeń motywu.

<?php
/**
 * Title: Footer credits
 * Slug: lw-base/footer-credits
 * Categories: footer
 * Block Types: core/template-part/footer
 * Description: Short credit line for the site footer.
 *
 * @package lw-base
 */

?>
<!-- wp:paragraph {"fontSize":"small"} -->
<p class="has-small-font-size"><?php esc_html_e( 'Published with a block theme.', 'lw-base' ); ?></p>
<!-- /wp:paragraph -->

Plik styles/night.json udostępnia ciemny wariant kolorystyczny. Po wyborze i zapisaniu w edytorze witryny wybrane wartości trafiają do bazy danych jako dostosowanie. Późniejsza aktualizacja pliku nie zmienia zatem automatycznie tych zapisanych wartości.

{
	"$schema": "https://schemas.wp.org/wp/7.1/theme.json",
	"version": 3,
	"title": "Night",
	"settings": {
		"color": {
			"palette": [
				{ "slug": "base", "color": "#0a0e14", "name": "Base" },
				{ "slug": "contrast", "color": "#e5e7eb", "name": "Contrast" },
				{ "slug": "accent", "color": "#38bdf8", "name": "Accent" }
			]
		}
	}
}

Dlaczego zmiana pliku może być niewidoczna?

Edytor witryny zapisuje zmienione szablony w bazie: całe strony jako wp_template, części jako wp_template_part, a globalne ustawienia wyglądu jako wp_global_styles. Takie rekordy nie są publicznymi wpisami blogowymi. Pusty rekord globalnych stylów może powstać już przy otwarciu edytora.

Każde dostosowanie należy do aktywnego motywu. Powiązanie wp_theme zawiera nazwę katalogu tego motywu, na przykład lw-child. Identyfikator szablonu, taki jak lw-child//index, łączy nazwę motywu z nazwą szablonu.

Zapisane dostosowanie index ma pierwszeństwo przed plikiem templates/index.html tego motywu. Aktualizacja pliku może więc pozostać niewidoczna. Usunięcie dostosowania przywraca wersję plikową, jeżeli plik istnieje. Szablonu istniejącego wyłącznie w pliku nie można usunąć tą operacją. Poniższe polecenia WP-CLI tylko odczytują dane: pokazują rekordy i motyw przypisany do przykładowego rekordu. Liczba 123 zastępuje rzeczywisty identyfikator rekordu.

# Which templates, template parts and global styles live in the database?
wp post list --post_type=wp_template,wp_template_part,wp_global_styles --post_status=any --fields=ID,post_type,post_name,post_modified

# Which theme (stylesheet) does a customization belong to? 123 = an ID from the list above.
wp post term list 123 wp_theme --fields=name

Po zmianie motywu wcześniejsze dostosowania pozostają zapisane przy poprzednim motywie. Po powrocie mogą ponownie działać. Eksport z edytora witryny tworzy natomiast ZIP z plikami motywu i uwzględnionymi dostosowaniami, w tym połączonymi ustawieniami wyglądu.

Który szablon ma pierwszeństwo?

WordPress najpierw szuka najlepiej dopasowanego szablonu. Dla zwykłego pojedynczego wpisu kolejność może wyglądać tak: single-post-witaj-swiecie, single-post, single, singular, index. Najpierw występują bardziej szczegółowe nazwy, a następnie ogólniejsze szablony zastępcze.

Dla tej samej nazwy najpierw liczy się zapisane dostosowanie, potem plik motywu potomnego, a następnie plik motywu nadrzędnego. Gdy brak pasującego pliku motywu, mogą też działać szablony wtyczek zarejestrowane przez register_block_template(), dostępne od WordPressa 6.7. Bez dopasowania wyszukiwanie przechodzi do kolejnej nazwy. Filtry rozszerzeń mogą zmieniać ten standardowy sposób wyszukiwania.

Przykład: single.html motywu nadrzędnego ma pierwszeństwo przed zapisanym dostosowaniem index. Najpierw decyduje dokładniejsza nazwa; źródło rozstrzyga dopiero między takimi samymi nazwami. Części, takie jak header, nie używają listy coraz ogólniejszych nazw. Dla wskazanej nazwy części obowiązuje kolejność: baza danych, plik motywu potomnego, plik motywu nadrzędnego. Rejestr całych szablonów wtyczek nie stanowi dodatkowego kroku tego wyszukiwania części.

template-canvas.php wyświetla wybrane bloki. Od wersji 6.8 pusty zapisany szablon powoduje wyświetlenie informacji po zalogowaniu. Bez logowania WordPress używa wersji plikowej, jeśli istnieje.

Dodanie motywu potomnego

Motyw potomny wymaga style.css z polami Theme Name i Template. Wartość Template musi dokładnie odpowiadać nazwie katalogu motywu nadrzędnego. Osobny index.html nie jest potrzebny, ponieważ WordPress może znaleźć plik motywu nadrzędnego.

lw-child/
├── style.css
├── theme.json
└── parts/
    └── header.html

/*
Theme Name: LW Child
Template: lw-base
Description: Child theme of LW Base with its own palette and header.
Version: 1.0.0
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: lw-child
*/

Pliki o takich samych nazwach w templates/ i parts/ zastępują wersje nadrzędne. Wzorce są dopasowywane według Slug w nagłówku pliku, a warianty wyglądu według nazwy pliku w styles/. Niezastąpione pliki motywu nadrzędnego pozostają dostępne. Poniższy nagłówek motywu potomnego dodaje opis witryny:

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
	<!-- wp:group {"layout":{"type":"flex","orientation":"vertical"}} -->
	<div class="wp-block-group">
		<!-- wp:site-title /-->
		<!-- wp:site-tagline /-->
	</div>
	<!-- /wp:group -->
	<!-- wp:navigation /-->
</div>
<!-- /wp:group -->

Dostosowania edytora należące do motywu nadrzędnego nie działają po przejściu na motyw potomny. Jednak dostosowania zapisane wcześniej dla tego motywu potomnego mogą natychmiast wrócić. Dopiero brak takich dostosowań oznacza, że wynik zależy wyłącznie od nowej wersji plikowej.

Jakie ustawienia dziedziczy motyw potomny?

WordPress łączy ustawienia w kolejności: własne wartości domyślne, ustawienia zarejestrowanych bloków, wartości motywu i na końcu zapisane dostosowania. Dla tej samej właściwości wygrywa późniejsza wartość. W ustawieniach motywu wersja potomna uzupełnia lub zastępuje wartości nadrzędne. Ustawienia theme.json mają też pierwszeństwo przed odpowiednimi ustawieniami add_theme_support().

{
	"$schema": "https://schemas.wp.org/wp/7.1/theme.json",
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{ "slug": "base", "color": "#f4f6f9", "name": "Base" },
				{ "slug": "contrast", "color": "#111827", "name": "Contrast" },
				{ "slug": "accent", "color": "#c2410c", "name": "Accent" }
			]
		}
	},
	"styles": {
		"elements": {
			"heading": {
				"typography": { "fontWeight": "700" }
			}
		}
	}
}

W przykładzie pozostają szerokości układu, rozmiary czcionek i kolor odnośników z motywu nadrzędnego. Motyw potomny dodaje pogrubione nagłówki. Ważny wyjątek dotyczy palet: paleta potomna zastępuje całą paletę nadrzędną. Podobnie działają inne listy gotowych wartości, takie jak rozmiary i rodziny czcionek oraz cienie, w obrębie tego samego źródła ustawień.

Dlatego motyw potomny zawiera wszystkie trzy kolory. Przy samym accent zabrakłoby tutaj zmiennych base i contrast. Reguły tła i tekstu nie mogłyby wtedy zastosować przewidzianych kolorów. Poniższe zapytanie pokazuje paletę motywu bez zapisanych dostosowań użytkownika:

wp eval 'echo wp_json_encode( wp_get_global_settings( array( "color", "palette", "theme" ), array( "origin" => "base" ) ), JSON_PRETTY_PRINT );'

"origin" => "base" pomija zapisane dostosowania. Pozostałe dane domyślne, blokowe i motywu nadal są przetwarzane; mogą też działać filtry rozszerzeń. Ścieżka color → palette → theme ogranicza wynik do palety motywu.

Zakres testów i praktyczna kontrola

Archiwalne testy z 30 września 2026 na WordPressie 7.1.2 dokumentują aktywację, dziedziczenie, walidację edytora, pierwszeństwo szablonów i zastępowanie palety w pierwotnym przykładzie. Dodany szablon pełnej treści należy do obecnej poprawki. Przed użyciem w witrynie oddzielna instalacja testowa powinna objąć widok listy, pojedynczy wpis, stronę i zapisane dostosowanie edytora.

Istotne są dwa ograniczenia techniczne: szablon PHP motywu potomnego może mieć pierwszeństwo przed blokowym szablonem nadrzędnym o tej samej nazwie. Filtr wp_theme_json_data_theme działa także przed połączeniem osobnego pliku JSON motywu potomnego z plikiem nadrzędnym. Pełne odziedziczone wartości nie są więc jeszcze dostępne na tym etapie.

Powiązany artykuł opisuje aktualizację bezpieczeństwa szablonów stron w WordPressie 7.1.2.