wp_list_categories() │ WP 2.1.0

Выводит список категорий в виде ссылок. Если перейти по ссылке, то будут показаны все посты из категории.

Возвращает

null|Строку|false. HTML код если echo=1. Если echo=0 вернет HTML код в переменную для дальнейшей обработки.

Шаблон использования

$args = array(
	'show_option_all'    => '',
	'show_option_none'   => __('No categories'),
	'orderby'            => 'name',
	'order'              => 'ASC',
	'style'              => 'list',
	'show_count'         => 0,
	'hide_empty'         => 1,
	'use_desc_for_title' => 0,
	'child_of'           => 0,
	'feed'               => '',
	'feed_type'          => '',
	'feed_image'         => '',
	'exclude'            => '',
	'exclude_tree'       => '',
	'include'            => '',
	'hierarchical'       => true,
	'title_li'           => __( 'Categories' ),
	'number'             => NULL,
	'echo'               => 1,
	'depth'              => 0,
	'current_category'   => 0,
	'pad_counts'         => 0,
	'taxonomy'           => 'category',
	'walker'             => 'Walker_Category',
	'hide_title_if_empty' => false,
	'separator'          => '<br />',
);

echo '<ul>';
	wp_list_categories( $args );
echo '</ul>';

Использование

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

Аргументы параметра $args

• child_of (число)
• current_category (строка/массив)
• depth (число)
• echo (логический)
• exclude (строка)
• exclude_tree (строка)
• include (строка / массив)
• hide_empty (логический)
• hide_title_if_empty (логический)
• hierarchical (логический)
• order (строка)
• orderby (строка)
• separator (строка)
• show_count (логический)
• show_option_all (строка)
• show_option_none (строка)
• style (строка)
• taxonomy (строка)
• title_li (строка)
• use_desc_for_title (логический)
• number (число)
• pad_counts (логический)
• feed (логический)
• feed_type (строка)
• feed_image (строка)
• walker (объект)

child_of(число)

Показать дочерние категории. В параметре указывается ID родительской категории (категория, вложенные категории которой нужно показать).

current_category(строка/массив)

ID категории или массив из ID. К которым нужно добавить класс current-cat (class="current-cat"). Это нужно, чтобы подсветить категорию через CSS стили.

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

С версии 4.4. в этот параметр можно передавать массив ID.
По умолчанию: ''

depth(число)

Этот параметр контролирует глубину вложенности категорий, которые будут показаны. По умолчанию 0- показывать все уровни вложенности (все дочерние категорий). С версии 2.5.

• 0 - все уровни вложенности (По умолчанию);
• -1 - показать все дочерние категории, но без вложенности li списков. Отменяет параметр hierarchical;
• 1 - показать только категории первого уровня (все виды вложенных категорий не будут показываться);
• n - число - глубина вложенности которую нужно показывать. 2 - покажет категорий первого и второго уровня.

echo(логический)

Выводить на экран или возвращать для обработки.

• 1 (true) - да, выводить на экран;
• 0 (false) - нет, просто возвратить данные.

По умолчанию: true

exclude(строка)

Исключить категории из списка. Нужно указывать ID категорий через запятую.

• Если этот параметр указан, параметр child_of будет отменен.
• Если параметр heiararchical=true, то будет исключаться вся ветка. Если heiararchical=false, то для исключения ветки используйте параметр exclude_tree.

По умолчанию: ''

exclude_tree(строка)

Исключить дерево категорий из списка. Указывайте ID категорий через запятую. Параметр include должен быть пустым. Если параметр heirarchical=true, то используйте exclude вместо exclude_tree.
По умолчанию: ''

include(строка / массив)

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

hide_empty(логический)

Скрывать ли категории в которых нет записей?

• 0 (false) - показывать пустые (не скрывать);
• 1 (true) - не показывать пустые категории (скрывать).

По умолчанию: 1

hide_title_if_empty(логический)

Нужно ли прятать $title_li если в списке нет элементов. С версии 4.4.
По умолчанию: false (всегда будет показываться)

hierarchical(логический)

Показывать категории как дерево. Показывать вложенные (дочерние категории), как вложенный список.

• 1 (true) - да, древовидный тип отображения;
• 0 (false) - нет, показать сплошным типом.

По умолчанию: true

order(строка)

Направление сортировки:

• ASC - по порядку, от меньшего к большему (1, 2, 3; a, b, c);
• DESC - в обратном порядке, от большего к меньшему (3, 2, 1; c, b, a).

По умолчанию: 'ASC'

orderby(строка)

Сортировка списка по определенным критериям. Например по количеству постов в каждой категории или по названию категорий. Доступны следующие критерии:

• ID - сортировка по ID;
• name - сортировка по названию (по умолчанию);
• slug - сортировка по алт. имени (slug);
• count - по количеству записей в категории;
• term_group - по группе.

По умолчанию: 'name'

separator(строка)

Разделитель между элементами. С версии 4.4.
По умолчанию: '<br />'

show_count(логический)

Показывать/нет количество записей в категории. Число записей будет показано после названия категории в скобках (например, Психология (16)).

• 1 (true) - показывать количество записей;
• 0 (false) - не показывать количество записей.

show_option_all(строка)

Текст для отображения всех категорий.

Если передать не пустую строку, например 'Все категории', то в список будет добавлена ссылка на все категории (часто это ссылка на главную страницу блога). Текстом ссылки станет текст переданный параметру, в данном случае Все категории.
По умолчанию: ''

show_option_none(строка)

Если функция не нашла ни одной категории для показа, то будет показан этот текст.
По умолчанию: 'Нет рубрик'

style(строка)

Стиль вывода списка.

• list - означает, что нужно выводить списком в теге <li>, вложенность категорий будет соблюдена.
• none - будут выведены только ссылки на категории (<a>) разделенные тегом <br>.

По умолчанию: 'list'

taxonomy(строка)

Название таксономии, которую нужно обрабатывать.
По умолчанию: 'category'

title_li(строка)

Установить заголовок списка. Если изменить этот параметр на '' (title_li=), то заголовок не будет выводиться вовсе.
По умолчанию: 'Категории'

use_desc_for_title(логический)

Вставлять ли описание категории в атрибут title у ссылки (<a title="Описание категории" href="...):

• 1 (true) - да, вставлять описание в title, если оно есть;
• 0 (false) - нет, не использовать описание (будет: Посмотреть все записи в рубрике "название категории").

По умолчанию: false

number(число)

Установить максимальное количество отображаемых категорий (SQL LIMIT). По умолчанию выводится без ограничений.
По умолчанию: ''

pad_counts(логический)

Считать общее количество постов во вложенных категориях и показывать это число рядом с родительской категорией. Параметр включается автоматически при включенных show_count и hierarchical.
По умолчанию: 0 (false)

feed(логический)

Показать ли рядом с названием ссылку на RSS фид (rrs-2) категории. Текст переданный в этом параметре станет текстом ссылки.
По умолчанию: ''

feed_type(строка)

Тип фида
По умолчанию: 'rss-2'

feed_image(строка)

Показать ли рядом с названием ссылку-картинку на RSS фид (rrs-2) категории. В параметре нужно указать ссылку на картинку. Если этот параметр указан, параметр $feed будет отменен.
По умолчанию: ''

walker(объект)

Расширение объекта (класса), который предназначен для создание списка категорий. Передаваемый параметру объект - это расширение для класса Walker_Category или Walker.
По умолчанию: 'Walker_Category'

Примеры

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

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

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

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

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

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

<ul>
   <?php wp_list_categories('orderby=name&show_count=1&feed_image=/images/rss.gif'); ?>
</ul>

<?php
// список разделов произвольной таксономии genre

$args = array(
  'taxonomy'     => 'genre', // название таксономии
  'orderby'      => 'name',  // сортируем по названиям
  'show_count'   => 0,       // не показываем количество записей
  'pad_counts'   => 0,       // не показываем количество записей у родителей
  'hierarchical' => 1,       // древовидное представление
  'title_li'     => ''       // список без заголовка
);
?>

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

li.categories { ... }  /* общий селектор */
li.cat-item { ... }
li.cat-item-7 { ... }  /* Рубрика с ID 7 */
li.current-cat { ... }
li.current-cat-parent { ... }
ul.children { ... }

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

Добавить свой пример

Заметки

Добавленные параметры в разных версиях:

• 2.3.0 — echo
• 2.5.0 — depth
• 2.6.0 — current_category
• 2.7.1 — exclude_tree
• 2.9 — pad_counts
• 3.0 — taxonomy
• 4.4 — hide_title_if_empty и separator. current_category стал не обязательным