Функция register_theme_feature() в WordPress позволяет регистрировать различные возможности (фичи) темы, которые можно активировать с помощью функции add_theme_support(). Она определяет, какие типы данных поддерживает та или иная функция, и позволяет контролировать, какие фичи доступны через REST API.
register_theme_feature() не активирует функцию в теме, а лишь описывает её параметры и возможности, такие как тип данных и необходимость показа через REST API. Эта функция полезна для создания кастомных возможностей темы, которые можно включать и отключать по мере необходимости.
register_theme_feature( string $feature, array $args = array() ): true|WP_Error
Параметры
- $feature (строка) — Уникальное имя, идентифицирующее фичу. Обычно совпадает с названием, используемым в
add_theme_support(). - $args (массив) — Опции фичи:
- type — Тип данных (
string,boolean,integer,number,array,object). По умолчаниюboolean. - variadic — Использует ли функция несколько аргументов (должен быть
true, еслиtypeравенarray). - description — Краткое описание фичи для REST API.
- show_in_rest — Будет ли фича доступна через REST API (
true,falseили массив сschema). - schema — JSON-схема, описывающая структуру данных, если
type—arrayилиobject. - name — Альтернативное имя, используемое в REST API.
- prepare_callback — Функция для форматирования фичи в REST API.
- type — Тип данных (
Возвращаемое значение
- Возвращает
true, если фича была успешно зарегистрирована, или объектWP_Errorв случае ошибки.
Пример 1: Регистрация базовой фичи типа boolean
В этом примере создаем простую фичу под названием custom-logo-support для поддержки логотипа в теме.
register_theme_feature( 'custom-logo-support', array(
'type' => 'boolean',
'description' => 'Enables custom logo support for the theme',
'show_in_rest' => true
) );
Теперь фича custom-logo-support зарегистрирована, и её можно включить с помощью add_theme_support( 'custom-logo-support' ).
Пример 2: Регистрация фичи с кастомной схемой
Создаем фичу custom-background-options для настройки фона, которая будет доступна через REST API. Определим схему для параметра фичи array.
register_theme_feature( 'custom-background-options', array(
'type' => 'array',
'variadic' => true,
'description' => 'Array of options for custom background settings',
'show_in_rest' => array(
'schema' => array(
'type' => 'array',
'items' => array(
'type' => 'string'
)
)
)
) );
В этом примере для show_in_rest указана JSON-схема, которая описывает массив строк.
Пример 3: Регистрация фичи с типом object и кастомным именем
Создадим фичу theme-layout-settings с типом данных object, которая будет иметь альтернативное имя в REST API.
register_theme_feature( 'theme-layout-settings', array(
'type' => 'object',
'description' => 'Theme layout settings configuration',
'show_in_rest' => array(
'schema' => array(
'type' => 'object',
'properties' => array(
'layout' => array(
'type' => 'string',
'enum' => array( 'boxed', 'wide' ),
'default' => 'wide'
),
'columns' => array(
'type' => 'integer',
'default' => 3
)
)
),
'name' => 'layoutSettings'
)
) );
Эта фича добавит настройку с альтернативным именем layoutSettings в REST API и позволит задавать свойства layout и columns.
Пример 4: Регистрация фичи с кастомной функцией форматирования для REST API
В этом примере добавляем фичу advanced-color-palette, которая включает палитру цветов с использованием функции форматирования для REST API.
register_theme_feature( 'advanced-color-palette', array(
'type' => 'array',
'description' => 'Advanced color palette for theme customization',
'show_in_rest' => array(
'schema' => array(
'type' => 'array',
'items' => array(
'type' => 'string'
)
),
'prepare_callback' => 'custom_palette_prepare_callback'
)
) );
function custom_palette_prepare_callback( $palette ) {
// Кастомная обработка палитры перед отправкой в REST API
return array_map( 'strtoupper', $palette );
}
Функция custom_palette_prepare_callback преобразует все значения палитры в верхний регистр перед отправкой через REST API.
Пример 5: Регистрация фичи с несколькими аргументами и вариативной поддержкой
В этом примере создается фича custom-slider-support с типом array, поддерживающая несколько аргументов.
register_theme_feature( 'custom-slider-support', array(
'type' => 'array',
'variadic' => true,
'description' => 'Support for custom slider functionality',
'show_in_rest' => false
) );
Здесь variadic установлен в true, что позволяет использовать эту фичу с разными параметрами.
Заключение
Функция register_theme_feature() является мощным инструментом для разработчиков, который позволяет создавать кастомные фичи для тем и настраивать их доступность в REST API. Эти фичи можно легко включать и выключать через add_theme_support(). Благодаря гибкости register_theme_feature(), разработчики могут создавать уникальные настройки и функции, которые будут полностью соответствовать потребностям темы.