Функция register_taxonomy()
позволяет создавать новые таксономии в WordPress или изменять уже существующие. Таксономии используются для группировки записей по определенным признакам. Это могут быть, например, категории или метки, а также произвольные таксономии, созданные разработчиками для расширения функционала.
register_taxonomy( string $taxonomy, array|string $object_type, array|string $args = array() ): WP_Taxonomy|WP_Error
Важно: не используйте эту функцию до хука init
.
Параметры
- $taxonomy — строка, ключ таксономии. Не может превышать 32 символов и должен состоять из строчных букв, цифр, дефисов и подчеркиваний.
- $object_type — тип или массив типов объектов, для которых регистрируется таксономия. Например,
'post'
,'page'
, или ваш собственный кастомный тип записей. - $args — массив аргументов, которые настраивают поведение таксономии. Ниже рассмотрим ключевые из них.
Аргументы $args
:
- label (строка): Название таксономии во множественном числе для админки.
- description (строка): Краткое описание таксономии.
- labels (массив): Массив меток для отображения в интерфейсе.
name
: Имя таксономии (обычно во множественном числе).singular_name
: Название для одного элемента.menu_name
: Название для меню.search_items
: Текст для поиска элементов.popular_items
: Популярные элементы.all_items
: Все элементы.parent_item
: Родительский элемент (для древовидных таксономий).edit_item
: Редактировать элемент.update_item
: Обновить элемент.add_new_item
: Добавить новый элемент.view_item
: Посмотреть элемент.new_item_name
: Название нового элемента.separate_items_with_commas
: Разделять элементы запятыми (не для древовидных).add_or_remove_items
: Добавить или удалить элементы.choose_from_most_used
: Выбрать из часто используемых.not_found
: Сообщение «не найдено».back_to_items
: Перейти к элементам.
- public (логический): Доступна ли таксономия для публичного использования.
- show_ui (логический): Отображать ли интерфейс для управления таксономией.
- show_in_menu (логический): Показывать ли таксономию в админ-меню.
- show_in_nav_menus (логический): Доступна ли таксономия в навигационном меню.
- show_tagcloud (логический): Показывать виджет облака тегов.
- show_in_rest (логический) (с WP 4.7): Включать ли таксономию в REST API.
- rest_base (строка) (с WP 4.7): Ярлык для REST API.
- rest_controller_class (строка) (с WP 4.7): Класс контроллера REST API.
- rest_namespace (строка) (с WP 5.9): Пространство имен в URL REST API маршрута.
- hierarchical (логический): Таксономия иерархическая (категории) или неиерархическая (теги).
- update_count_callback (строка): Название функции для подсчета терминов.
- rewrite (массив/false): Переписывать ли URL для таксономии.
slug
: Часть URL для таксономии.with_front
: Включать ли префикс ссылки.hierarchical
: Древовидная структура ссылок.ep_mask
: Маска конечной точки для красивых ссылок.
- publicly_queryable (логический): Доступна ли таксономия для запросов на сайте.
- query_var (строка/логический): Параметр для запросов таксономии.
- capabilities (массив): Права доступа для управления таксономией.
manage_terms
,edit_terms
,delete_terms
,assign_terms
.
- meta_box_cb (строка): Callback-функция для отображения метабокса таксономии.
- meta_box_sanitize_cb (callable): Функция для очистки данных таксономии.
- show_admin_column (логический): Показать ли колонку таксономии в таблице постов.
- show_in_quick_edit (логический): Отображать ли таксономию в быстром редактировании.
- sort (логический): Запоминать ли порядок терминов при прикреплении к постам.
- default_term (строка/массив) (с WP 5.5): Термин по умолчанию.
- _builtin (логический): Внутренняя таксономия WordPress (не для обычного использования).
Избегайте зарезервированных терминов
При создании пользовательских таксономий важно избегать использования зарезервированных терминов WordPress, таких как category
, tag
, post
, author
, и других. Использование зарезервированных слов может вызвать конфликт и некорректную работу сайта.
- attachment
- attachment_id
- author
- author_name
- calendar
- cat
- category
- category__and
- category__in
- category__not_in
- category_name
- comments_per_page
- comments_popup
- custom
- customize_messenger_channel
- customized
- cpage
- day
- debug
- embed
- error
- exact
- feed
- fields
- hour
- link_category
- m
- minute
- monthnum
- more
- name
- nav_menu
- nonce
- nopaging
- offset
- order
- orderby
- p
- page
- page_id
- paged
- pagename
- pb
- perm
- post
- post__in
- post__not_in
- post_format
- post_mime_type
- post_status
- post_tag
- post_type
- posts
- posts_per_archive_page
- posts_per_page
- preview
- robots
- s
- search
- second
- sentence
- showposts
- static
- status
- subpost
- subpost_id
- tag
- tag__and
- tag__in
- tag__not_in
- tag_id
- tag_slug__and
- tag_slug__in
- taxonomy
- tb
- term
- terms
- theme
- title
- type
- types
- w
- withcomments
- withoutcomments
- year
Пример 1: Создание таксономии для «Жанры фильмов»
В этом примере создается таксономия для записи типа movies
, которая будет использоваться для классификации фильмов по жанрам. Важно отметить, что в этом примере также включена поддержка REST API.
add_action( 'init', 'create_movie_genre_taxonomy' );
function create_movie_genre_taxonomy() {
register_taxonomy( 'movie_genre', ['movies'], [
'labels' => [
'name' => 'Movie Genres',
'singular_name' => 'Movie Genre',
'search_items' => 'Search Movie Genres',
'all_items' => 'All Movie Genres',
'edit_item' => 'Edit Movie Genre',
'update_item' => 'Update Movie Genre',
'add_new_item' => 'Add New Movie Genre',
'new_item_name' => 'New Movie Genre Name',
'menu_name' => 'Genres',
],
'description' => 'Genres to classify different types of movies',
'public' => true,
'show_in_rest' => true,
'hierarchical' => true, // Древовидная таксономия, как категории
'rewrite' => [ 'slug' => 'movie-genre' ],
]);
}
Здесь:
- Таксономия называется
movie_genre
. - Привязана к типу записи
movies
. - Параметр
hierarchical
установлен вtrue
, чтобы таксономия вела себя как древовидная структура (как категории). - Включена поддержка REST API (
show_in_rest => true
), что делает таксономию доступной в редакторе блоков.
Пример 2: Таксономия для «Уровней сложности рецептов»
Теперь создадим таксономию для классификации рецептов по уровню сложности.
add_action( 'init', 'create_recipe_difficulty_taxonomy' );
function create_recipe_difficulty_taxonomy() {
register_taxonomy( 'recipe_difficulty', ['recipes'], [
'labels' => [
'name' => 'Recipe Difficulty',
'singular_name' => 'Difficulty Level',
'search_items' => 'Search Difficulty Levels',
'all_items' => 'All Difficulty Levels',
'edit_item' => 'Edit Difficulty Level',
'update_item' => 'Update Difficulty Level',
'add_new_item' => 'Add New Difficulty Level',
'new_item_name' => 'New Difficulty Level',
'menu_name' => 'Difficulty Levels',
],
'public' => true,
'hierarchical' => false, // Таксономия недревовидная, как теги
'show_in_rest' => true,
'rewrite' => [ 'slug' => 'difficulty-level' ],
]);
}
Здесь таксономия recipe_difficulty
недревовидная, что делает её аналогом меток (тегов).
Пример 3: Таксономия для «Тэгов книг»
Далее пример создания пользовательской таксономии для типов книг, которая будет использоваться для меток книг в блоге.
add_action( 'init', 'create_book_tag_taxonomy' );
function create_book_tag_taxonomy() {
register_taxonomy( 'book_tag', ['books'], [
'labels' => [
'name' => 'Book Tags',
'singular_name' => 'Book Tag',
'search_items' => 'Search Book Tags',
'all_items' => 'All Book Tags',
'edit_item' => 'Edit Book Tag',
'update_item' => 'Update Book Tag',
'add_new_item' => 'Add New Book Tag',
'new_item_name' => 'New Book Tag',
'menu_name' => 'Tags',
],
'public' => true,
'hierarchical' => false, // Таксономия будет недревовидной
'show_in_rest' => true,
'rewrite' => [ 'slug' => 'book-tag' ],
]);
}
Таксономия book_tag
создана для типа записей books
и будет использоваться для добавления тэгов к книгам.
Настройка прав доступа (capabilities)
В некоторых случаях необходимо настроить права доступа к управлению элементами таксономии. Например, можно ограничить редактирование и удаление таксономий только для администраторов.
add_action( 'init', 'create_special_taxonomy' );
function create_special_taxonomy() {
register_taxonomy( 'special_category', ['post'], [
'labels' => [
'name' => 'Special Categories',
],
'public' => true,
'hierarchical' => true,
'capabilities' => [
'manage_terms' => 'manage_options', // Только администраторы могут управлять терминами
'edit_terms' => 'manage_options',
'delete_terms' => 'manage_options',
'assign_terms' => 'edit_posts', // Редакторы могут назначать термины
],
'rewrite' => [ 'slug' => 'special-category' ],
]);
}
В этом примере добавлена настройка прав доступа, чтобы только администраторы могли управлять терминами.
Регистрация нескольких таксономий для конкретного типа записи
/**
* Регистрация нескольких таксономий для типа записи 'book'.
*/
function wpdocs_create_multiple_taxonomies() {
$taxonomies = array(
array(
'name' => 'Genre',
'slug' => 'genre',
'hierarchical' => true,
),
array(
'name' => 'Writer',
'slug' => 'writer',
'hierarchical' => false,
),
);
foreach ( $taxonomies as $taxonomy ) {
register_taxonomy( $taxonomy['slug'], 'book', array(
'label' => __( $taxonomy['name'], 'textdomain' ),
'rewrite' => array( 'slug' => $taxonomy['slug'] ),
'hierarchical' => $taxonomy['hierarchical'],
'show_in_rest' => true,
) );
}
}
add_action( 'init', 'wpdocs_create_multiple_taxonomies', 0 );
Заключение
Функция register_taxonomy()
является мощным инструментом для создания и настройки таксономий в WordPress. Она позволяет группировать и структурировать данные с помощью произвольных категорий и меток, а также расширять функционал WordPress под конкретные нужды сайта.