DOM-иерархия в WordPress: как PHP-шаблоны и Gutenberg формируют структуру страницы
DOM-структура страницы WordPress - это результат сборки разметки из PHP-шаблонов темы и HTML-разметки блоков Gutenberg, а не отражение файловой структуры темы. Файлы header.php, single.php и footer.php лежат отдельно, в браузере они становятся единым деревом узлов. Контроль над этой сборкой определяет устойчивость CSS, скриптов и доступности.
Что получает браузер
DOM (Document Object Model) - это объектное представление документа, с которым работает браузер после разбора HTML. HTML - текст разметки, DOM - дерево узлов, построенное из него.
Для работы с WordPress-темой достаточно трех понятий:
- элемент - узел-тег (article, div, p);
- текстовый узел - текст внутри элемента;
- отношения - родитель и дочерние элементы, предки и потомки, соседние элементы.
Браузер строит DOM на основе HTML-разметки, учитывая правила HTML-парсинга. Поэтому итоговое дерево не всегда буквально повторяет исходную последовательность тегов. Парсер исправляет часть ошибок разметки, автоматически закрывает отдельные элементы и перестраивает некорректно вложенные конструкции. Откуда HTML пришел - из одного PHP-файла или из пяти подключенных частей - браузер не знает. Поэтому отладка по файлам темы и отладка по вкладке Elements в DevTools дают разную картину. Вторая показывает реальность.
Три разные иерархии
В разговорах о WordPress смешиваются три независимые структуры. Их полезно разделять.
| Понятие | Что определяет | Где видно |
|---|---|---|
| Иерархия шаблонов WordPress | какой PHP-файл выбран для текущего запроса | single.php, page.php, archive.php, правило Template Hierarchy |
| Иерархия блоков Gutenberg | как блоки вложены в редакторе | Group, Columns, Cover в редакторе |
| DOM-иерархия | итоговая структура узлов в браузере | вкладка Elements в DevTools |
Иерархия шаблонов выбирает точку входа. Иерархия блоков задает фрагменты разметки внутри контента. DOM-иерархия - итог: склеенная страница целиком, включая шапку, контент и подвал. Изменение в любой из первых двух меняет третью, но не один в один. Один блок Group в редакторе может превратиться в несколько вложенных div в браузере, один вызов get_template_part() - в целое поддерево элементов.
Материал посвящен классическим темам WordPress с использованием блоков Gutenberg.
Как PHP-шаблоны складываются в одно дерево
Классический single.php обычно не содержит страницу целиком. Он собирает ее:
<?php get_header(); ?>
<main class="site-main">
<?php while ( have_posts() ) : the_post(); ?>
<article class="entry">
<h1 class="entry-title"><?php the_title(); ?></h1>
<div class="entry-content"><?php the_content(); ?></div>
</article>
<?php endwhile; ?>
</main>
<?php get_footer(); ?>
get_header() подключает header.php, get_footer() - footer.php, get_template_part( 'parts/card' ) - повторяемый фрагмент карточки. Сам вызов get_template_part() подключает PHP-файл, а поддерево в итоговом DOM появляется, если подключенный файл выводит HTML. Каждый такой вывод добавляет свое поддерево в общий документ.
Отсюда типовые последствия:
- лишний div в подключаемой части повторяется на каждой карточке в цикле и раздувает дерево в десятки раз;
- незакрытый тег в header.php ломает вложенность всего, что идет ниже, включая контент;
- дублирование структурных элементов может возникнуть на разных уровнях сборки: в основном шаблоне, подключаемой части или разметке блока. Поэтому проверять нужно итоговый DOM, а не только PHP-файлы.
Правило простое: структурные теги (main, article, заголовок записи) должны встречаться в сборке в предсказуемом месте без дублей. Обертки в частях шаблонов нужны только если они несут класс компонента, семантику или layout-функцию.
Откуда Gutenberg берет лишние обертки
Каждый блок Gutenberg рендерит свой HTML, вложенные блоки - вложенный HTML. Вложенные блоки могут формировать дополнительные уровни HTML-разметки. Количество оберток зависит от реализации каждого блока.
Точная разметка зависит от версии WordPress и Gutenberg, настроек блока и поддержки темы, поэтому пример ниже - один из возможных вариантов, а не гарантированный вывод ядра. Структура группы с двумя абзацами может выглядеть так:
<div class="wp-block-group">
<p>Первый абзац</p>
<p>Второй абзац</p>
</div>
В других конфигурациях между внешней оберткой и абзацами появляется внутренний контейнер, добавляются классы выравнивания, фона или отступов. Перед сверкой примера со своим сайтом стоит открыть реальный HTML блока во вкладке Elements.
Блоки-контейнеры добавляют больше всего уровней:
- Group - внешняя обертка, в части конфигураций плюс внутренний контейнер;
- Columns и Column - обертка колонок, обертка каждой колонки, иногда внутренние контейнеры под выравнивание;
- Cover - обертка с фоном, внутренняя обертка контента, отдельный элемент под оверлей.
Визуальная группировка в редакторе не равна семантике. Три абзаца в одной Group выглядят как единый смысловой блок, но в простейшем варианте это контейнер с параграфами внутри без собственной семантики. Если группе нужен смысл раздела, ей нужен заголовок и, в зависимости от контекста, section через настройку тега или кастомный блок, а не только фон и отступы.
Практический вывод: перед стилизацией нового блока стоит один раз посмотреть его реальный HTML во вкладке Elements, а не предполагать его по виду в редакторе. Разметка ядра меняется между релизами, дополнительные обертки появляются и исчезают.
Как вложенность влияет на CSS
Селектор читает DOM-цепочку буквально. Три записи ниже выбирают разное:
.entry-content p { color: #222; }
.entry-content > p { color: #222; }
.entry-content .wp-block-group p { color: #222; }
Первый выбирает все параграфы внутри контента на любой глубине. Второй - только непосредственные дочерние параграфы, параграфы внутри Group уже не попадут. Третий - только параграфы внутри групп.
Глубокая привязка к структуре дает два эффекта. Стили ломаются при перестройке блоков пользователем: достаточно вынуть абзац из Group - и правило .entry-content .wp-block-group p перестает применяться. Поддержка дорожает: чтобы понять одно правило, приходится восстанавливать всю цепочку оберток.
Устойчивее опираться на классы компонентов, а не на глубину:
.card__text { line-height: 1.6; }
.card__text p { margin: 0 0 1em; }
Здесь изменение оберток Gutenberg вокруг карточки не ломает текст внутри, пока класс компонента на месте. Вложенность используется точечно - для состояния или варианта (card--wide .card__text), а не как основной способ адресации.
Как вложенность влияет на JavaScript
Типовые задачи в теме - найти родителя, перебрать дочерние элементы, повесить обработчик на список карточек:
const card = button.closest('.card');
const items = list.querySelectorAll('.card');
closest() поднимается вверх до ближайшего совпадения, querySelector() ищет вниз по поддереву. Оба метода зависят от наличия класса-якоря, но не от точной глубины.
Жесткая привязка к глубине делает скрипт хрупким:
// сломается при добавлении любой обертки между карточкой и кнопкой
button.parentNode.parentNode.querySelector('p');
Делегирование событий снимает часть зависимости от структуры: один обработчик на контейнере обслуживает все кнопки внутри, включая кнопки, добавленные позже внутрь того же контейнера, на котором установлен обработчик. В обработчике нужна проверка типа цели: event.target в общем случае может оказаться не элементом, а текстовым узлом, прямой вызов closest() на нем будет некорректен:
list.addEventListener('click', (event) => {
const target = event.target;
if (!(target instanceof Element)) return;
const btn = target.closest('[data-fav]');
if (!btn || !list.contains(btn)) return;
btn.closest('.card')?.classList.toggle('is-fav');
});
Здесь скрипту нужны только два условия: атрибут data-fav на кнопке и класс card на карточке. Сколько div между ними - не имеет значения.
Семантика - это не про внешний вид
Страница может выглядеть правильно и иметь некорректную структуру. Визуальный порядок не гарантирует правильный порядок заголовков, один div с классом кнопки не становится кнопкой для клавиатуры и скринридера.
Минимальный набор для темы:
- по спецификации HTML в документе не должно быть более одного элемента main без состояния hidden;
- article для записи, nav для навигации, header и footer для шапки и подвала страницы и записи по назначению, а не как нейтральные обертки;
- последовательная иерархия заголовков без необоснованных скачков уровней: уровень определяется структурой содержимого, вложенные секции могут требовать свой подуровень, пропуск уровня ради визуального размера - признак проблемы;
- интерактивные элементы не вкладываются друг в друга: кнопка внутри ссылки ломает активацию с клавиатуры.
Скринридер читает именно DOM-порядок и семантику тегов, а не визуальную сетку. Переставленные через CSS колонки с неверным порядком в DOM будут озвучены в неверном порядке. Проверка здесь - навигация по странице только с клавиатуры, проход по заголовкам, сверка порядка чтения с визуальным порядком и проверка доступных имен у кнопок и ссылок: имя должно объяснять действие без опоры на окружающий текст.
Как проверить структуру за пять минут
- Открыть страницу во фронтенде.
- Открыть DevTools, вкладка Elements.
- Найти компонент через инспектор и подняться вверх по цепочке родителей до body, фиксируя каждый уровень.
- Сопоставить цепочку с источниками: что пришло из header.php и footer.php, что - из шаблона, что - из the_content().
- Проверить дубли структурных тегов, иерархию заголовков, порядок чтения и доступные имена интерактивных элементов.
Пункт про "Просмотр кода страницы" отдельно: он показывает исходный HTML ответа сервера. Вкладка Elements показывает живой DOM после работы браузера и скриптов. Для Gutenberg-страниц с интерактивными блоками смотреть нужно именно Elements.
Частые ошибки и короткий чек-лист
Типовой набор проблем в кастомных темах:
- обертки без функции, оставшиеся после рефакторинга;
- div там, где нужен section, article, nav или заголовок;
- цепочки из 6-8 уровней ради одного визуального отступа;
- CSS только через длинные цепочки: .site-main .wrap .content .entry .group p;
- JS через parentNode.parentNode вместо closest() по классу;
- дубли структурных тегов из-за сборки из нескольких уровней: шаблон, часть шаблона, блок.
Чек-лист перед сдачей темы:
- каждый компонент находится по одному классу без повтора всей цепочки;
- извлечение блока из Group не ломает его стили и скрипты;
- в документе не более одного элемента main без состояния hidden, иерархия заголовков последовательна;
- интерактивные элементы доступны с клавиатуры, порядок чтения совпадает с визуальным, у кнопок и ссылок есть понятные доступные имена;
- у каждой обертки есть роль: класс компонента, семантика или layout-функция, бесхозные уровни удалены.
DOM-структура - та часть темы, которую нельзя поправить только стилями. Продуманная сборка из шаблонов и блоков сокращает отладку CSS и JS на всем сроке жизни сайта.
