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

Motyw blokowy (Block Theme) składa się przede wszystkim z plików HTML ze znacznikami bloków i jednego pliku JSON. Żeby zrozumieć jego działanie, trzeba też wiedzieć, który szablon WordPress wybiera dla danego żądania, dlaczego zmieniony plik czasem nie daje widocznego efektu i co dzieje się z ustawieniami motywu nadrzędnego, gdy motyw potomny (Child Theme) dodaje własny plik theme.json. Decyduje o tym kilka funkcji w rdzeniu WordPressa.

Artykuł pokazuje budowę małego, ale kompletnego motywu blokowego z plikami style.css i theme.json, jednym szablonem, dwoma częściami szablonu (Template Parts), jednym wzorcem (Pattern) i jedną wariacją stylu (Style Variation), a następnie motywu potomnego. Na podstawie kodu źródłowego WordPressa 7.1 wyjaśnia, gdzie Site Editor zapisuje zmiany, w jakiej kolejności wybierane są szablony i jak łączą się warstwy danych globalnych ustawień i stylów. Według API wersji WordPress.org aktualnym wydaniem w dniu 29.09.2026 jest 7.1.2.

Pliki minimalnego Block Theme

WordPress uznaje Theme za blokowy, gdy znajdzie czytelny plik templates/index.html. Metoda WP_Theme::is_block_theme() sprawdza dokładnie tę ścieżkę, a ze względu na zgodność wstecz także starszą block-templates/index.html. Reszta jest technicznie opcjonalna, choć bez niej trudno o użyteczny Theme. Folder przykładowego Theme’u wygląda tak:

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

Plik style.css zawiera nagłówek Theme’u. W Block Theme nie musi mieć żadnego CSS, bo wygląd definiuje theme.json. Theme Handbook wymienia jako pola wymagane w katalogu Theme’ów: Theme Name, Description, Version, Author, Text Domain, Tested up to, Requires at least, Requires PHP, License i License URI. Przykład ustawia Requires at least: 6.6, ponieważ korzysta z theme.json w wersji 3, wprowadzonej w WordPressie 6.6.

/*
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
*/

Nazwy folderów są stałe: Templates trafiają do templates/, Template Parts do parts/, wzorce do patterns/, a wariacje stylu do styles/. Dawne nazwy block-templates/ i block-template-parts/ nadal są rozpoznawane przez WP_Theme::get_block_template_folders(), ale wyłącznie jako rozwiązanie awaryjne dla starszych Theme’ów.

theme.json: settings, styles i wersja 3

Plik theme.json ma dwie główne sekcje. settings określa, co oferuje edytor: palety kolorów, rozmiary i rodziny czcionek, szerokości układu oraz włączone narzędzia projektowe. styles przypisuje konkretne wartości całej stronie, elementom takim jak linki i nagłówki oraz poszczególnym Blockom. Na najwyższym poziomie dochodzą customTemplates, templateParts i patterns; schemat JSON dla 7.1 zawiera ponadto title, slug, description i blockTypes, potrzebne przy wariacjach stylu.

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

Numer wersji ma znaczenie. Dokumentacja referencyjna theme.json na developer.wordpress.org opisuje wersję 3, a według Block Editor Handbook wprowadzono ją w WordPressie 6.6. W kodzie 7.1 stała WP_Theme_JSON::LATEST_SCHEMA również ma wartość 3. Dev note na make.wordpress.org opisuje jedyną zmianę łamiącą zgodność: od wersji 3 Theme nie zastępuje już po cichu domyślnych rozmiarów czcionek ani odstępów, gdy użyje ich slugów. Kto chce przypisać własne wartości slugom small, medium i large, musi ustawić defaultFontSizes (lub defaultSpacingSizes) na false, tak jak w przykładzie. Starsze wersje według Block Editor Handbook nadal są obsługiwane.

Klucz $schema występuje w dwóch wariantach: https://schemas.wp.org/trunk/theme.json podąża za rozwojem, a https://schemas.wp.org/wp/7.1/theme.json jest przypisany do konkretnego wydania. Funkcja eksportu w rdzeniu zapisuje formę z numerem wersji i ta forma jest też bezpieczniejsza dla podpowiedzi w edytorze kodu, bo schemat z gałęzi trunk może już opisywać właściwości, których zainstalowane wydanie nie zna. Wszystkie trzy pliki JSON z tego artykułu zostały zwalidowane względem schematu dla 7.1.

Tablica templateParts nadaje każdemu plikowi w parts/ tytuł i obszar (area). Rdzeń definiuje obszary header, footer i uncategorized; od wersji 7.0 kod źródłowy zawiera także navigation-overlay. Obszar decyduje, gdzie Site Editor pokazuje dany Part i jaki element HTML go otacza, jeśli nie ustawiono tagName.

Templates, Template Parts i wzorzec

Template to plik HTML z zserializowanymi Blockami. Poniższy index.html osadza nagłówek i stopkę, otacza treść elementem main i używa Blocku Query Loop z "inherit":true. Dzięki temu pokazuje to, co zwraca główne zapytanie danego żądania: listę wpisów bloga, archiwum albo wyniki wyszukiwania.

<!-- 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"} /-->

Template Parts są wstawiane przez slug. Atrybut theme celowo pominięto. Funkcja renderująca Blocku Template Part bez tego atrybutu sięga po get_stylesheet(), czyli aktywny Theme. Gdyby Theme nadrzędny wpisał tam na sztywno własny slug, przy aktywnym Child Theme zapytanie przestałoby pasować, a Part zostałby wyrenderowany jako pusty ciąg znaków. Dopiero brak atrybutu pozwala Child Theme zastąpić dany Part.

<!-- 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 nie zawiera własnego tekstu, tylko ładuje wzorzec. Pliki wzorców w patterns/ WordPress rejestruje automatycznie na init, o ile nagłówek pliku zawiera co najmniej Title i Slug; pliki bez tych pól rdzeń odrzuca komunikatem _doing_it_wrong(). Ponieważ plik jest w PHP, teksty da się tłumaczyć z użyciem Text Domain Theme’u, czego czysty szablon HTML nie umożliwia.

<?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 -->

Wariacja stylu to niepełny plik theme.json w folderze styles/, zawierający tylko różnice względem pliku głównego. Gdy ktoś wybierze ją w Site Editorze, jej dane według Theme Handbook trafiają do bazy danych jako dostosowanie użytkownika. Późniejsze zmiany w pliku wariacji nie docierają więc do witryn, które już ją zapisały.

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

Co Site Editor zapisuje w bazie danych

Dopóki nikt niczego nie zmienia, WordPress czyta pliki Theme’u bezpośrednio. Gdy Template zostanie zapisany w Site Editorze, rdzeń przechowuje pełny markup Blocków jako wpis. Biorą w tym udział trzy typy wpisów: wp_template dla Templates, wp_template_part dla Template Parts oraz wp_global_styles dla zmian w stylach globalnych, łącznie z wybraną wariacją stylu. Pole post_name wpisu z Template to jego slug, na przykład index lub single.

Taksonomia wp_theme przypisuje te wpisy do motywu. Jej termem jest stylesheet, czyli nazwa folderu aktywnego motywu. Przy aktywnym motywie potomnym liczy się jego folder, a nie folder motywu nadrzędnego. get_block_templates() pobiera wyłącznie wpisy, których term odpowiada get_stylesheet(). Części szablonu mają dodatkowo term taksonomii wp_template_part_area. Wewnętrznie każdy szablon ma identyfikator w postaci stylesheet//slug, na przykład lw-child//index.

Wniosek jest prosty: zapisany Template wygrywa z plikiem o tym samym slugu. get_block_templates() najpierw pobiera wyniki z bazy, a ich slugi przekazuje jako slug__not_in do wyszukiwania plików, więc plik Theme’u w ogóle nie jest już brany pod uwagę. Jeśli aktualizacja Theme’u zmieni później templates/index.html, zmiana pozostanie niewidoczna, dopóki dostosowanie nie zostanie usunięte. Kontroler REST dla Templates pozwala usuwać tylko Templates o źródle custom; w przypadku Template opartego na pliku Theme’u usunięcie wpisu przywraca wersję z pliku. Listę dostosowań na danej witrynie da się uzyskać przez WP-CLI:

# 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

Ponieważ zapytanie filtruje po termie stylesheet, zmiana Theme’u nie usuwa tych wpisów, a jedynie wyłącza ich działanie: zostają w bazie pod starym termem i znowu obowiązują, gdy ten Theme zostanie ponownie włączony. Eksport z Site Editora, zaimplementowany w wp_generate_block_templates_export_file(), tworzy archiwum ZIP z plikami Theme’u, aktualnymi Templates i Parts oraz plikiem theme.json, w którym dane Theme’u połączono z danymi użytkownika.

Rozwiązywanie Template: baza danych, Child, Parent, fallback

Hierarchia szablonów w Block Theme jest taka sama jak w klasycznych Theme’ach; Theme Handbook zaznacza jedynie, że pliki HTML zastępują pliki PHP. Dla pojedynczego wpisu WordPress tworzy listę kandydatów, na przykład single-post-witaj-swiecie, single-post, single, singular i index. locate_block_template() przekazuje tę listę do resolve_block_template(), które wywołuje get_block_templates() dla wszystkich kandydatów, a potem sortuje wyniki według pozycji w hierarchii.

Dla każdego slugu obowiązuje stała kolejność źródeł. Najpierw liczy się wpis wp_template dla aktywnego stylesheet. Następnie _get_block_templates_files() czyta folder templates/ Child Theme przed folderem Theme’u nadrzędnego; slug znaleziony w Child jest w Parent pomijany. Dalej są Templates, które wtyczki rejestrują od WordPressa 6.7 funkcją register_block_template(), ale tylko wtedy, gdy nie istnieje plik Theme’u o tym samym slugu. Sam WordPress nie dostarcza żadnych szablonów HTML dla Theme’ów, więc właściwym fallbackiem rdzenia jest kolejny, mniej szczegółowy slug w hierarchii, aż do index.html.

Najbardziej szczegółowy slug zawsze wygrywa, niezależnie od źródła. Plik single.html w Theme nadrzędnym ma więc pierwszeństwo przed index.html zmienionym w Site Editorze, bo single stoi w hierarchii przed index. Kolejność źródeł rozstrzyga wyłącznie między wpisami o tym samym slugu. Template Parts działają według tego samego wzorca: funkcja renderująca Blocku Template Part szuka najpierw wpisu wp_template_part, a potem wywołuje get_block_file_template(), które przez _get_block_template_file() przeszukuje najpierw katalog stylesheet, a potem katalog template.

Znaleziony markup Blocków jest wyświetlany przez wp-includes/template-canvas.php. Jeśli zapisany Template jest pusty, zalogowani użytkownicy od wersji 6.8 widzą komunikat z linkiem do Site Editora; odwiedzający dostają zamiast tego treść pliku Theme’u, o ile taki plik istnieje.

Child Theme dla Block Theme

Child Theme bezwzględnie potrzebuje tylko pliku style.css z nagłówkiem Template. Według Theme Handbook jego wartość musi dokładnie odpowiadać nazwie folderu Theme’u nadrzędnego. Przykładowy Child Theme wnosi dodatkowo własną paletę i zmieniony nagłówek.

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
*/

Własny plik templates/index.html w Child Theme nie jest potrzebny. WP_Theme::get_file_path() szuka najpierw w katalogu stylesheet, a potem w katalogu template, dlatego is_block_theme() znajduje plik Theme’u nadrzędnego i również Child Theme traktuje jako blokowy. Wszystko, czego brakuje w Child, pochodzi z Parent: Templates, Template Parts, wzorce i wariacje stylu.

Nadpisywanie działa element po elemencie. Plik o tej samej nazwie w templates/ lub parts/ zastępuje wersję z Theme’u nadrzędnego. W przypadku wzorców funkcja _register_theme_block_patterns() nie patrzy na nazwę pliku, tylko na Slug w nagłówku: wzorce Child Theme są rejestrowane jako pierwsze, a wzorzec z Parent o zajętym już slugu zostaje pominięty. Przy wariacjach stylu get_style_variations() porównuje nazwy plików w obu folderach styles/ i przy zgodności zachowuje tylko plik z Child. Zastąpiony nagłówek w Child Theme wygląda tak:

<!-- 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 -->

Z termu stylesheet wynika jeszcze jeden praktyczny szczegół. Dostosowania wykonane w Site Editorze przy aktywnym Theme nadrzędnym należą do jego stylesheet. Po przełączeniu na Child Theme przestają obowiązywać, a Child startuje od plików.

Jak łączone są pliki theme.json z Parent i Child

Globalne ustawienia i style pochodzą z czterech źródeł, które WP_Theme_JSON_Resolver::get_merged_data() łączy w stałej kolejności: default (własny theme.json rdzenia), blocks (dane z rejestracji Blocków), theme oraz custom (dane użytkownika z wpisu wp_global_styles). Każda kolejna warstwa nadpisuje wcześniejsze. Dokumentacja w kodzie podaje przykład koloru tła dla Blocku akapitu ustawionego zarówno przez Theme, jak i przez użytkownika: wygrywa ustawienie użytkownika.

Warstwa theme sama składa się z kilku części. get_theme_data() najpierw czyta theme.json aktywnego Theme’u, czyli Child. Jeśli istnieje Theme nadrzędny z innym plikiem theme.json, resolver tworzy z pliku Parent obiekt WP_Theme_JSON i scala do niego dane Child; według komentarza w kodzie pierwszeństwo ma Child. Na koniec wynik jest nakładany na wartości z add_theme_support(), więc theme.json wygrywa z Theme Supports.

{
	"$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" }
			}
		}
	}
}

Samo scalanie, czyli WP_Theme_JSON::merge(), korzysta z array_replace_recursive(), więc zagnieżdżone obiekty są łączone klucz po kluczu. W przykładzie układ, typografia i kolor linków z motywu nadrzędnego pozostają bez zmian, a motyw potomny dodaje grubość czcionki nagłówków.

Wyjątkiem są presety: palety, gradienty, filtry duotone, rozmiary i rodziny czcionek oraz pozostałe listy presetów, na przykład rozmiary odstępów i cienie. Każda z tych list jest zastępowana w całości. Paleta motywu potomnego zastępuje więc paletę motywu nadrzędnego, zamiast ją rozszerzać.

Dlatego motyw potomny powtarza wszystkie trzy slugi. Gdyby podał wyłącznie accent, zabrakłoby base i contrast, a każdy styl odwołujący się do nich straciłby wartość. Obowiązującą paletę motywu warto sprawdzić na instalacji testowej:

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

Opcja "origin" => "base" pomija warstwę użytkownika, więc wynik pokazuje wyłącznie połączone dane Parent i Child.

Ograniczenia i otwarte kwestie

• Filtr wp_theme_json_data_theme otrzymuje dane Child, zanim zostanie do nich dołączony plik Parent. Callback, który oczekuje kompletnych danych Theme’u, przy aktywnym Child Theme widzi tylko część pochodzącą z Child.
• Rozwiązania mieszane z szablonami PHP podlegają dodatkowym regułom. Gdy locate_template() znajdzie plik PHP, w grę wchodzą tylko Templates blokowe o tej samej lub wyższej szczegółowości, a szablon PHP w Child może mieć pierwszeństwo przed Template blokowym o tym samym slugu w Parent.
• Theme Handbook opisuje nadpisywanie wzorców w Child Theme plikiem o tej samej nazwie, natomiast kod 7.1 porównuje slugi. Artykuł opiera się na kodzie źródłowym.
• Niektóre strony Handbooka w przykładach nadal pokazują "version": 2, choć dokumentacja referencyjna opisuje wersję 3.
• Przykłady przetestowano 30.09.2026 w WordPressie 7.1.2: oba motywy aktywują się bez komunikatów, Child Theme bez własnego index.html jest rozpoznawany jako Block Theme, znaczniki bloków przechodzą walidację w Site Editorze, a pierwszeństwo szablonów, skutki zmiany motywu i zastępowanie palety działają zgodnie z opisem. Pokrewny temat porusza artykuł o luce bezpieczeństwa w szablonach stron, załatanej w WordPressie 7.1.2.