wp_list_categories() в WordPress: Полное руководство с примерами

Функция wp_list_categories() в WordPress позволяет выводить или получать HTML-список категорий на сайте. Это мощный инструмент для организации контента и улучшения навигации. В этой статье мы рассмотрим параметры функции, примеры использования и различные сценарии, в которых она может быть полезна.

wp_list_categories( array|string $args = '' ): void|string|false

Параметры

• $args (array|string) — Необязательный. Массив или строка дополнительных аргументов, используемых для настройки вывода. См. get_categories(), get_terms() и WP_Term_Query::__construct() для информации о других доступных аргументах.

Параметры $args

• child_of (число)
  Показывает дочерние категории. В параметре указывается ID родительской категории, вложенные категории которой нужно показать.
• current_category (строка/массив)
  ID категории или массив из ID, к которым нужно добавить класс current-cat (class=»current-cat»). По умолчанию: ''.
• depth (число)
  Контролирует глубину вложенности категорий, которые будут показаны.
  • 0 — все уровни вложенности (по умолчанию);
  • -1 — показать все дочерние категории, но без вложенности li списков;
  • 1 — показать только категории первого уровня;
  • n — число, глубина вложенности, которую нужно показывать.
• echo (логический)
  Выводить на экран или возвращать для обработки.
  • 1 (true) — выводить на экран;
  • 0 (false) — возвратить данные.
    По умолчанию: true.
• exclude (строка)
  Исключить категории из списка, указывая ID категорий через запятую.
  По умолчанию: ''.
• exclude_tree (строка)
  Исключить дерево категорий из списка, указывая ID категорий через запятую.
  По умолчанию: ''.
• include (строка/массив)
  Вывести списком только указанные категории.
  По умолчанию: ''.
• hide_empty (логический)
  Скрывать ли категории без записей?
  • 0 (false) — показывать пустые;
  • 1 (true) — не показывать пустые.
    По умолчанию: 1.
• hide_title_if_empty (логический)
  Нужно ли прятать $title_li, если в списке нет элементов.
  По умолчанию: false.
• hierarchical (логический)
  Показывать категории как дерево.
  • 1 (true) — да, древовидный тип отображения;
  • 0 (false) — нет, сплошным типом.
    По умолчанию: true.
• order (строка)
  Направление сортировки:
  • ASC — по порядку;
  • DESC — в обратном порядке.
    По умолчанию: 'ASC'.
• orderby (строка)
  Сортировка списка по определенным критериям. Доступны следующие критерии:
  • ID — по ID;
  • name — по названию (по умолчанию);
  • slug — по алт. имени (slug);
  • count — по количеству записей в категории;
  • term_group — по группе.
    По умолчанию: 'name'.
• separator (строка)
  Разделитель между элементами.
  По умолчанию: '<br />'.
• show_count (логический)
  Показывать/нет количество записей в категории.
  • 1 (true) — показывать количество записей;
  • 0 (false) — не показывать.
• show_option_all (строка)
  Текст для отображения всех категорий.
  По умолчанию: ''.
• show_option_none (строка)
  Если категории не найдены, показывать этот текст.
  По умолчанию: 'Нет рубрик'.
• style (строка)
  Стиль вывода списка:
  • list — выводить в теге <li>;
  • none — только ссылки на категории разделенные тегом <br>.
    По умолчанию: 'list'.
• taxonomy (строка)
  Название таксономии для обработки.
  По умолчанию: 'category'.
• title_li (строка)
  Установить заголовок списка.
  По умолчанию: 'Категории'.
• use_desc_for_title (логический)
  Вставлять ли описание категории в атрибут title у ссылки.
  По умолчанию: false.
• number (число)
  Установить максимальное количество отображаемых категорий.
  По умолчанию: ''.
• pad_counts (логический)
  Считать общее количество постов во вложенных категориях.
  По умолчанию: 0 (false).
• feed (логический)
  Показать ли ссылку на RSS фид категории.
  По умолчанию: ''.
• feed_type (строка)
  Тип фида.
  По умолчанию: 'rss-2'.
• feed_image (строка)
  Показать ли ссылку-картинку на RSS фид категории.
  По умолчанию: ''.
• walker (объект)
  Расширение объекта для создания списка категорий.
  По умолчанию: 'Walker_Category'.

Возвращаемое значение

• void|string|false — Возвращает null, если echo равно 1, HTML-список категорий, если echo равно 0. Вернет false, если таксономия не существует.

Базовый пример

Для простого вывода списка категорий:

<ul>
    <?php wp_list_categories(); ?>
</ul>

Этот код создаст стандартный список категорий с заголовком «Categories».

Пример 1: Сортировка по алфавиту

Чтобы отсортировать категории по алфавиту и включить только категории с определенными ID, используйте следующий код:

<ul>
    <?php wp_list_categories('orderby=name&include=3,5,9,16'); ?>
</ul>

Пример 2: Показать количество постов

Следующий пример сортирует категории по имени, показывает количество записей и исключает категорию с ID 10:

<ul>
    <?php wp_list_categories('orderby=name&show_count=1&exclude=10'); ?>
</ul>

Пример 3: Вывод только указанных категорий

Этот пример выводит категории с ID 9, 5 и 23 и изменяет заголовок списка:

<ul>
    <?php wp_list_categories('include=5,9,23&title_li=<h2>' . __('Poetry') . '</h2>'); ?>
</ul>

Пример 4: Показать только дочерние категории

Чтобы вывести только дочерние категории определенной категории, используйте следующий код:

<ul>
    <?php wp_list_categories('orderby=id&show_count=1&child_of=8'); ?>
</ul>

Пример 5: Удаление скобок из количества постов

Чтобы удалить скобки, в которые обрамляется количество постов:

<?php
$cats = wp_list_categories('echo=0&show_count=1&title_li=<h2>Категории</h2>');
$cats = str_replace(['(', ')'], '', $cats);
echo $cats;
?>

Пример 6: Показать ссылки на RSS-ленты

Для отображения категорий с ссылками на RSS-ленты:

<ul>
    <?php wp_list_categories('orderby=name&show_count=1&feed=RSS'); ?>
</ul>

Пример 7: Использование пользовательских таксономий

С версии 3.0 функция позволяет выводить списки пользовательских таксономий:

<?php
$args = array(
    'taxonomy' => 'genre',
    'orderby' => 'name',
    'show_count' => 0,
    'hierarchical' => true,
    'title_li' => ''
);
?>

<ul>
    <?php wp_list_categories($args); ?>
</ul>

Пример 8: Стилизация списка

Функция wp_list_categories() автоматически создает CSS-классы для элементов списка. Вы можете использовать их для стилизации:

li.categories { ... }  /* общий селектор */
li.cat-item { ... }
li.current-cat { ... }

Пример 9: Убрать заголовок списка

Чтобы убрать заголовок списка категорий, установите параметр title_li в пустую строку:

<ul>
    <?php wp_list_categories('exclude=4,7&title_li='); ?>
</ul>

Заключение

Функция wp_list_categories() предоставляет гибкий способ вывода категорий на сайте WordPress. С помощью различных параметров можно настроить вывод под конкретные требования вашего проекта. Вы можете комбинировать параметры, чтобы получить именно тот результат, который вам нужен.