Руководство по theme.json: кастомизируйте свою тему WordPress как профессионал

Экосистема WordPress продолжает развиваться, а потому разработчики WordPress получают все больше контроля над разными настройками и параметрами. Полное редактирование сайта (FSE) уравнивает возможности всех пользователей, позволяя создавать темы с нуля, особенно при использовании файла theme.json.

Разработчики также могут применять файл theme.json в своих целях. Этот конфигурационный файл позволяет детально настраивать тему WordPress без утомительной сложности и трудоемкости комплексных языков программирования.

В этом детальном руководстве мы рассмотрим возможности файла theme.json, в том числе связь с полным редактированием сайта (FSE). К концу статьи вы поймете, как использовать его возможности для создания современных, высокопроизводительных веб-сайтов независимо от вашего уровня технической подготовки.

Файл theme.json

По своей сути, theme.json — это конфигурационный файл, определяющий настройки и стили вашей темы WordPress. Он имеет формат JavaScript Object Notation (JSON), представляющий собой структурированные данные, наследующие пары ключ-значение родительского языка.

Файл theme.json имеет ключевое значение для управления различными аспектами вашей темы, куда относятся цветовые палитры, настройки типографики, параметры макета, стили для каждого блока, произвольные свойства CSS и многое другое. Более подробно об этих аспектах мы расскажем в этой статье.

Пусть он пока не выглядит слишком революционно, файл theme.json важен для будущего разработки WordPress. В следующем разделе объясняется, почему.

Почему файл theme.json важен для разработки тем WordPress

Обычно разработка тем и плагинов в WordPress сводилась к редактированию шаблонов с помощью PHP, использованию файла functions.php и другим техническим задачам.

Файл theme.json знаменует собой значительный сдвиг, особенно для разработки тем. Этому есть несколько причин:

• Файл представляет собой единое, организованное место для определения настроек и стилей вашей темы. Не нужно поддерживать массу разрозненных файлов CSS и PHP.
• Централизованный подход к объявлению стилей и настроек в theme.json позволяет WordPress генерировать более эффективный CSS. По сравнению с использованием фреймворков, таких как jQuery, существует некоторый потенциал для повышения производительности.
• Вы получаете больший контроль над стилем вашего сайта и отдельных блоков. Это демократизирует разработку тем для пользователей с меньшими техническими знаниями.
• По мере дальнейшего развития FSE файл theme.json будет играть решающую роль в том, как темы, глобальные стили (Global Styles) и блочный редактор (Block Editor) взаимодействуют друг с другом.

Сочетание всех этих аспектов позволяет получить стандартизированный способ определения настроек и стилей для вашей темы. Использование theme.json приводит к созданию более надежных, гибких и удобных для пользователя тем WordPress. Что немаловажно, эти творения будут полностью соответствовать курсу развития платформы.

Где найти файл theme.json

Во-первых, вы не найдете файл theme.json в «традиционных» (классических) темах. Этот файл поставляется только с блочными темами. Однако вы можете создать theme.json в любой теме, если вы используете WordPress 5.8+.

Обычно theme.json находится в каталоге wp-content/themes/[ ваша-тема ]. Если файла там нет, то откройте любимый редактор кода и создайте его при необходимости. Про содержимое пока не беспокойтесь, мы вернемся к этому чуть позже.

Если вам надо создать новый файл с нуля, но при этом вы хотите иметь перед глазами некоторый пример, вы можете воспользоваться стандартной темой Twenty Twenty-Four.

Она является блочной темой, а потому у нее есть файл theme.json. Откройте его и сверяйтесь с ним, чтобы лучше понять структуру правил.

Что вам понадобится для работы с файлом theme.json

Естественно, далеко не каждый пользователь сможет вот так просто открыть файл конфигурации и приступить к его заполнению. Вам потребуются некоторые базовые навыки и знания в области создания и кастомизации темы:

• Базовые знания JSON. Мы считаем, что вы его быстро освоите, но лучше заранее ознакомиться с его синтаксисом и структурой.
• Понимание CSS. Многие объекты и свойства JSON соответствуют своим аналогам в CSS. Знание CSS здесь будет преимуществом.
• Знание блочного редактора WordPress. Понимание того, как функционируют блоки, а также как они настраиваются, поможет вам в процессе разработки.

Пусть это и не является строго обязательным, но мы все же рекомендуем вам хотя бы на поверхностном уровне ознакомиться с ключевыми концепциями FSE (полного редактирования сайта), что поможет вам эффективнее использовать theme.json. Вы также сможете понять, как вносимые вами изменения влияют на отображение сайта. В некоторых случаях вам все равно потребуется обращаться к HTML и JavaScript для реализации вашего замысла.

Наконец, мы рекомендовали бы вам воспользоваться следующими техническими инструментами:

• Редактор кода. Выбор качественного редактора с подсветкой синтаксиса JSON и валидацией упрощает работу.
• Локальная среда разработки. Она поможет быстро тестировать изменения, не затрагивая продакшн.

Имея эти инструменты и знания, вы будете подготовлены к тому, чтобы начать настраивать свою тему WordPress с помощью theme.json.

Анатомия, структура и иерархия файла theme.json

Файл theme.json имеет определенную структуру, которую вам нужно будет понять. Он также содержит иерархию и некоторые уникальные элементы, требующие дополнительного разъяснения.

Эта часть, вероятно, является самой технически сложной, но даже в этом случае вы легко поймете все основные концепции.

Давайте начнем со структуры, а затем перейдем к другим элементам theme.json.

Базовая структура файла

Учитывая, что файл имеет формат JSON, вы, возможно, уже понимаете его общую структуру. Весь объект файла заключен в фигурные скобки, как и разные объекты внутри него. Каждый объект состоит из пар ключ-значение; для ключей используются одинарные или двойные кавычки, для завершения строки – запятые.

Минимальный файл theme.json должен содержать объекты version, settings и styles:

{
    "version": 2,
    "settings": {
      // Global settings go here
    },
    "styles": {
      // Global styles go here
    }
}

Объекты settings и styles достаточно просты и понятны, а вот version требует более подробного объяснения. Это значение должно быть целым числом, соответствующим версии API, которую вы используете для чтения вашего файла. Текущая версия API – 3. При этом версия 2 тоже распространена. Вы можете мигрировать с более старых версий к новой.

В большинстве файлов theme.json также имеется схема. Вкратце, она позволяет работать с автозавершением в редакторах кода и обеспечивает валидацию файла. Схема добавляется в самое начало файла:

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 2,
    "settings": {
    },
    "styles": {
    }
}

Далее вы будете добавлять разные свойства и объекты в settings и styles.

Иерархия

Файл theme.json имеет иерархическую структуру и представляет собой лишь один уровень общей иерархии настроек и стилей для вашего сайта. Если вы знакомы с CSS, вам будет проще понять его, поскольку по своей сложности файл напоминает CSS.

Изменения, внесенные вами в theme.json, не всегда могут отображаться во фронтенде вашего сайта. Пользовательские настройки имеют приоритет над всем остальным. Это означает, что любые изменения, внесенные на экране Appearance > Editor в WordPress, будут отображаться во фронтенде сайта:

Если вы используете дочернюю тему с файлом theme.json, то в таком случае этот файл переопределит все изменения, кроме тех, которые были внесены через редактор сайта. Аналогично, все, что вы определяете в конфигурационном файле родительской темы, перепишет базовые настройки и стили WordPress. Именно на theme.json родительской темы мы и остановимся в рамках данной статьи, хотя у самого WordPress тоже есть свой собственный файл theme.json.

Отметим еще, что вы можете переопределять значения с помощью хуков и фильтров. С помощью такой динамической фильтрации вы можете создавать плагины и темы, которые будут менять настройки и стили темы или платформы.

Грамматика блоков

Если вы перейдете в блочный редактор или в редактор сайта, откроете запись или страницу и включите редактор кода, вы заметите множество HTML-комментариев внутри контента:

Объясняется это просто: вместо PHP-файлов блочные темы используют HTML-файлы с комментариями и блочной разметкой. Сочетание этих элементов формирует «грамматику блоков», необходимую для написания файла theme.json.

Для контентных блоков, к примеру, для блока Paragraph, контент оборачивается следующим образом:

<!-- wp:paragraph -->
    <p>Content goes here!</p>
<!-- /wp:paragraph -->

В других случаях вам могут понадобиться только однострочные комментарии или комментарии, которые самозакрываются. В некоторых блоках вы можете комбинировать разные типы комментариев для создания макетов и дизайна. Вы также можете вкладывать комментарии друг в друга:

<!-- wp:columns -->
<div class="wp-block-columns">
    <!-- wp:column -->
        <div class="wp-block-column"></div>
    <!-- /wp:column -->
    

    <!-- wp:column -->
        <div class="wp-block-column"></div>
    <!-- /wp:column -->
</div>
<!-- /wp:columns -->

Здесь мы создали блок Columns, используя комментарий-обертку. В нем мы можем добавить HTML для оформления этих столбцов или включить отдельные обертки для столбцов. Во фронтенде все будет выглядеть тривиально, поскольку блоки часто находятся один внутри другого.

Чтобы найти разметку для конкретного блока, вы можете обратиться к руководству Block Editor Handbook. Однако самый простой способ – добавить блок в WordPress, открыть редактор кода и скопировать оттуда разметку.

Что касается изменений, которые вы можете внести в эту разметку, мы рассмотрим это в следующем разделе.

Как взаимодействуют theme.json и FSE

Из обсуждения иерархии вы уже поняли, что theme.json – это важная часть FSE. Оба компонента работают вместе, предлагая комплексное решение для настройки темизации в WordPress. К примеру, интерфейс глобальных стилей (Global Styles) – это, по сути, визуальное представление параметров вашего theme.json.

Вы можете модифицировать параметры либо в панели Global Styles, либо в конфигурационном файле, и WordPress обновит соответствующие значения по мере необходимости. Хотя настройки редактора сайта будут иметь приоритет, файл theme.json станет основой для собственных стилей вашей темы. Глобальные стили позволяют заменить ваши базовые настройки своими собственными без написания кода или редактирования файла theme.json.

Более того, произвольные свойства CSS, заданные в файле theme.json, будут доступны в интерфейсе глобальных стилей. Пользователи получают возможность редактировать эти свойства для более единообразного оформления своего сайта. Здесь же можно задавать конкретные стили и параметры для блоков, впоследствии настраиваемые из консоли WordPress.

Файл Theme.json обеспечивает более детальный и тонкий контроль над настройками, стилями и многим другим. Инструмент предназначен для разработчиков, предлагает более простой и удобный интерфейс, нежели классические подходы. Затем уже с помощью Global Styles можно легко настроить тему по своему вкусу. В дальнейшем вы увидите, как оба инструмента функционируют в тандеме, помогая создавать разнообразный дизайн и макеты сайтов.

Работа со свойствами файла theme.json

Изучив основы, вы сможете начать работу с объектами и свойствами файла theme.json. Мы не в состоянии рассмотреть все возможные варианты его применения или сценарии. Однако к концу этого урока вы сможете создавать темы, обладающие полной функциональностью и прекрасно выглядящие во фронтенде.

Settings

Свойство settings позволяет управлять тем, какие функции вы предлагаете в редакторе сайта и как они работают. Это свойство верхнего уровня, и обычно вы столкнетесь с несколькими уровнями вложенности.

Когда мы рассмотрим стили и их вариации, вы увидите, что между этими параметрами есть некоторое пересечение, но оба типа играют важную роль в создании темы.

Вам доступно ограниченное количество свойств:

{
    "version": 3,
    "settings": {
        "appearanceTools": false,
        "blocks": {},
        "border": {},
        "color": {},
        "custom": {},
        "dimensions": {},
        "layout": {},
        "position": {},
        "shadow": {},
        "spacing": {},
        "typography": {},
        "useRootPaddingAwareAlignments": false
    }
}

В официальном руководстве WordPress Theme Developer Handbook есть описание всех настроек (и стилей). Мы дадим краткий обзор нескольких важных настроек, требующих дополнительного пояснения:

• appearanceTools. Универсальное свойство, позволяющее использовать множество других; предназначено для экономии времени. Оно задает параметры границ, межстрочный интервал типографики, отступы, поля и многое другое.
• blocks. Хотя большая часть вашей работы будет связана с глобальными настройками и стилями, свойство blocks позволяет задавать это для каждого блока отдельно. В руководстве разработчика есть отличная документация по этому аспекту theme.json.
• custom. Уникальное свойство, не имеющее функциональности. Вы сами решаете, что оно делает. Его используют для создания произвольных свойств CSS для темы, его возможности очень широки.
• useRootPaddingAwareAlignments. Сложное свойство, которое мы не будем полностью рассматривать. По сути, оно помогает вам задавать стили горизонтальных отступов в вашей теме. Если вы хотите, чтобы элементы full-width растягивались до краев экрана, сохранив при этом отступы корневого элемента, – вам оно пригодится.

Обратите внимание: вам не нужно добавлять в theme.json те свойства, с которыми вы не планируете работать. К примеру, если вам не требуется appearanceTools, просто опустите его – не обязательно задавать его с параметром false.

Определяем settings в theme.json

Каждое свойство в settings имеет ряд подсвойств, представляющих собой пары ключ-значение. К примеру, цветовые палитры можно создать следующим образом:

{
    "version": 3,
    "settings": {
        "color": {
          "palette": [
            {
              "color": "#0073aa",
              "name": "Primary",
              "slug": "primary"
            },
            {
              "color": "#23282d",
              "name": "Secondary",
              "slug": "secondary"
            }
          ],
…

Другие свойства имеют простые булевы значения, которые позволяют включать или выключать эти возможности в редакторе сайта:

{
    "version": 3,
    "settings": {
        "color": {
            "background": true,
            "defaultPalette": true,
            "link": true,
            "text": true
        }
    }
}

После определения параметров вы можете применять к ним стили. Давайте рассмотрим это подробнее.

Стили и стилевые вариации

Если settings определяют доступ к конкретным опциям стилизации, свойство styles позволяет задавать глобальные стили для вашей темы. Опять же, это свойство верхнего уровня, которое будет содержать несколько уровней вложенности. Вы можете охватить конкретные элементы, блоки, использовать произвольные CSS-свойства.

Важно определить стили темы здесь, чтобы вы могли получить к ним доступ и кастомизировать их в редакторе сайта. Вы можете работать с рядом элементов:

{
    "version": 3,
    "styles": {
        "border": {},
        "color": {},
        "dimensions": {},
        "filter": {},
        "shadow": {},
        "spacing": {},
        "typography": {},
        "css": {}
    }
}

Многие из них вы нечасто будете использовать в виде свойств второго уровня. Некоторые из них будут применяться в основном к блокам и элементам. Пример:

…
"styles": {
    "blocks": {
        "core/group": {
            "color": {
                "text": "#000000",
                "background": "#ffffff",
                "link": "#777777"
            }
…

В контексте глобальных стилей вы будете работать с корневыми элементом – который соответствует тегу body вашей страницы. Для конкретных элементов вы можете использовать структуру, похожую на ту, что используют блоки, но только со свойством elements:

…
"styles": {
    "elements": {
        "button": {
            "color": {
                "text": "#ffffff",
                "background": "#aa3f33"
            }
…

Теперь все изменения, сделанные вами в редакторе сайта, можно будет увидеть во фронтенде. В разметке будет сгенерированный CSS для любых созданных вами стилей:

Обратите внимание, что вы также можете стилизовать псевдоклассы hover и focus:

…
"elements": {
    "button": {
        "color": {
            "text": "#ffffff",
            "background": "#aa3f33"
        },
        ":hover": {
            "color": {
                "background": "#822f27"
            }
…

Применение стилей – это еще более емкий по содержанию процесс.

Стилевые вариации

Прежде чем продолжить, давайте коснемся стилевых вариаций. Разные цветовые палитры и стили типографики вы можете увидеть в интерфейсе FSE:

Однако эти параметры не нужно записывать в theme.json. Вместо этого вы создаете альтернативные версии файла, даете им уникальные имена и сохраняете в каталоге styles вашей темы:

Обратите внимание, что заголовок в разметке уникален для каждого отдельного JSON-файла. Правда, это поле опциональное. Мы рекомендуем его использовать для большей ясности и лучшего опыта взаимодействия.

Произвольные шаблоны и фрагменты шаблонов

Подобно вариациям стилей, файл theme.json позволяет вам регистрировать произвольные шаблоны и связанные с ними части шаблона. Разметка очень проста:

"customTemplates": [
    {
        "name": "my-template",
        "title": "My Template",
        "postTypes": [
            "page",
            "post"
        ]
    }
]

Для свойства customTemplates необходимо определить три элемента:

• name. Соответствует шаблону, который вы создадите в каталоге templates вашей темы. К примеру, /template/my-template.html.
• title. Удобочитаемая человеческая версия названия шаблона.
• postTypes. Если не задано, то используется page, но вы можете указать массив типов записей, для которых подходит шаблон.

Пользователи смогут выбирать любые зарегистрированные вами шаблоны через блочный редактор или редактор сайта.

Что касается частей (фрагментов) шаблона, регистрировать их не обязательно, но мы советуем это сделать. Структура регистрации аналогична регистрации шаблонов:

…
"templateParts": [
    {
        "area": "header",
        "name": "header",
        "title": "Header"
    },
…

Здесь имя и заголовок соответствуют тем же определениям, что и в полных шаблонах. Область area указывает, к какой категории относится элемент: header, footer или uncategorized, но вы можете назначить элементы шаблона любой произвольной области.

Мы советуем вам также изучить, как вывести эти участки шаблона, поскольку без дополнительного кода они не будут видны.

Паттерны

Финальная часть: обсуждение блочных паттернов. Вы можете включить любое количество таких паттернов в theme.json с помощью массива верхнего уровня. Любой подходящий паттерн из библиотеки паттернов WordPress можно добавить в ваш файл:

Создать массив легко: вы используете свойство patterns и слаг соответствующего паттерна из URL:

С помощью слага вы можете заполнить разметку patterns:

{
    "version": 3,
    "patterns": [
        "fullwidth-vertically-aligned-headline-on-right-with-description-on-left"
    ]
}

Выбрать их можно через каталог паттернов в блочном редакторе:

Такой способ интеграции ресурсов библиотеки паттернов очень удобен и полезен. Это еще одна причина, почему файл theme.json стал излюбленным способом разработки WordPress-тем у различных авторов.

Порядок действий по кастомизации вашего WP-сайта с помощью theme.json

После того как вы разберетесь с ключевыми компонентами theme.json, вам нужно будет заточить ваши рабочие процессы под его применение. Это новый способ разработки тем, а потому он требует иного подхода, нежели классические методы.

Нам понадобится настроить URL схемы, выбрать версию API и определить глобальные параметры. Мы пропишем цветовую палитру, опции типографики и настройки макета. В большинстве случаев также будет полезно активировать appearanceTools:

"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
   "settings": {
"appearanceTools": true,
     "color": {
       "palette": [
         {
           "name": "Primary",
"slug": "primary",
           "color": "#0073aa"
         },
         {
      "name": "Secondary",
        "slug": "secondary",
           "color": "#23282d"
         }
       ]
     },
     "typography": {
"fluid": true,
       "fontSizes": [
         {
           "size": "13px",
           "slug": "small",
           "name": "Small"
         },
         {
"size": "16px",
           "slug": "normal",
           "name": "Normal"
…

Идем далее. Теперь мы можем создать произвольные CSS-свойства с помощью слагов. К примеру, можно установить свои варианты толщины шрифта:

…
"custom": {
    "fontWeight": {
        "light": 300,
        "regular": 400,
        "medium": 500,
        "bold": 700
    },
…

Переходим к стилям.

…
"styles": {
    "color": {
        "background": "var(--wp--preset--color--base)",
        "text": "var(--wp--preset--color--main)"
    },
…

Настраиваем стили блоков (может иметь вид огромного списка):

…
"styles": {
    "block": {
        "core/separator": {
            "color": {
            "text": "var(--wp--preset--color--main)"
            },
        "typography": {
            "fontSize": "var(--wp--preset--font-size--large)"
            }
        },
        "core/site-tagline": {
            "spacing": {
                "margin": {
                    "bottom": "20px"
                }
            },
            "typography": {
                "fontSize": "var(--wp--preset--font-size--small)"
            }
        },
        "core/site-title": {
            "typography": {
                "fontSize": "var(--wp--preset--font-size--medium)",
                "fontWeight": "var(--wp--custom--font-weight--semi-bold)",
                "lineHeight": "var(--wp--custom--line-height--none)"
        },
…

Наконец, мы можем разработать какие-либо произвольные шаблоны и фрагменты шаблонов. Их тоже нужно будет зарегистрировать в theme.json. На этом же этапе регистрируются и любые блочные паттерны.

Использовать theme.json или FSE – ваш выбор

Учитывая взаимосвязь theme.json и FSE, вы можете задаться вопросом, почему следует использовать один инструмент, а не другой. На самом деле, оба подходят для разных сценариев и должны применяться совместно.

Например, theme.json будет вашим основным инструментом в следующих ситуациях:

• Вы разрабатываете темы и создаете новую тему с нуля.
• JSON — это язык, который вы понимаете и с которым вам удобно работать.
• Вам нужен программный метод определения дефолтных стилей и настроек для вашей темы.
• Стили и настройки, которые вы хотите реализовать, требуют большего управления, нежели то, которое предлагается по умолчанию в редакторе сайта.

Конечно, последний пункт довольно нишевый, ибо FSE практически полностью повторяет функциональность theme.json.

Полное редактирование сайта будет более целесообразным для большинства пользователей в следующих сценариях:

• Вы владелец сайта, который хочет кастомизировать существующую тему.
• JSON вам незнаком.
• Визуальные интерфейсы больше подходят для вашего рабочего процесса кастомизации и разработки.
• Вы хотите быстро вносить изменения без необходимости активного кодирования.

На практике для темы потребуется конфигурационный файл, определяющий её основные параметры. Затем устанавливается иерархия, и владельцы сайтов могут использовать FSE для дальнейшей кастомизации.

Источник: kinsta.com