Главная / Блог / DOM-иерархия в WordPress

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 будут озвучены в неверном порядке. Проверка здесь - навигация по странице только с клавиатуры, проход по заголовкам, сверка порядка чтения с визуальным порядком и проверка доступных имен у кнопок и ссылок: имя должно объяснять действие без опоры на окружающий текст.

Как проверить структуру за пять минут

  1. Открыть страницу во фронтенде.
  2. Открыть DevTools, вкладка Elements.
  3. Найти компонент через инспектор и подняться вверх по цепочке родителей до body, фиксируя каждый уровень.
  4. Сопоставить цепочку с источниками: что пришло из header.php и footer.php, что - из шаблона, что - из the_content().
  5. Проверить дубли структурных тегов, иерархию заголовков, порядок чтения и доступные имена интерактивных элементов.

Пункт про "Просмотр кода страницы" отдельно: он показывает исходный 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 на всем сроке жизни сайта.

Частые вопросы

Чтобы не пропустить новые материалы

Короткий дайджест вечером в понедельник. Без спама.

Выберите, что получать

Обсудим ваш проект

Расскажите о вашем бизнесе, покажите текущий сайт или просто опишите задачу в свободной форме. Я изучу вводные, предложу решение и сориентирую по срокам и смете.

Отвечаю в течение нескольких часов в рабочее время.

Защита от спама – Yandex SmartCaptcha

Если вам удобнее обсудить всё текстом без заполнения форм – напишите напрямую: в Telegram или на sergei@kruglov.net

Удобнее голосом? Напишите пару слов о задаче - договоримся об удобном времени созвона на 15-20 минут, и я пришлю свой номер телефона.