wp_list_pages() в WordPress: Полный Гид

Функция wp_list_pages() в WordPress предназначена для вывода списка страниц в виде ссылок. Она полезна для создания навигационных меню, часто размещаемых в таких частях сайта, как шапка (header.php) или боковая панель (sidebar.php).

Функция основана на get_pages(), которая получает все страницы, а затем форматирует их в виде HTML-списка. Она также служит основой для функции wp_page_menu().

wp_list_pages( array|string $args = '' )

Параметры

Функция wp_list_pages() предлагает множество параметров для настройки вывода списка страниц:

• depth (число): Управляет уровнем вложенности отображаемых страниц.
  • 0 (по умолчанию): Включает все уровни вложенных страниц и отображает их в древовидном виде.
  • -1: Включает все уровни вложенных страниц, но отображает их как общий список без древовидного отображения.
  • 1, 2, 3 и т.д.: Отображает страницы только на указанном уровне вложенности, например, 1 для дочерних страниц первого уровня, 2 для второго уровня и так далее.
• show_date (строка): Управляет отображением даты рядом со ссылкой.
  • » (по умолчанию): Не отображает даты.
  • modified: Показывает дату последнего изменения.
  • created: Показывает дату создания страницы.
• date_format (строка): Определяет формат даты, если параметр show_date включен. Например, d/m/Y покажет дату в формате 10/11/2011. По умолчанию используется формат даты, заданный в настройках WordPress.
• child_of (число): Отображает только дочерние страницы указанной страницы. Указывается ID родительской страницы. По умолчанию 0, что означает отображение всех страниц.
• exclude (строка): Указывает ID страниц, которые следует исключить из списка. ID разделяются запятыми, например: exclude=3,7,31. По умолчанию пусто.
• exclude_tree (строка): Исключает указанные страницы и все их дочерние страницы из списка. Указывается ID страниц, разделенные запятыми. Этот параметр исключает целое дерево страниц. Добавлен в версии 2.7. По умолчанию пусто.
• include (строка/массив): Показывает только указанные страницы. ID указываются через запятую или пробел, например: include=45,63,78. Этот параметр заменяет параметры exclude, child_of, depth, meta_key, meta_value, и authors.
• title_li (строка): Устанавливает заголовок списка. По умолчанию используется __('Pages'), что обеспечивает локализацию. Если оставить пустым (''), заголовок не будет отображаться, и HTML-теги <ul> и </ul> будут удалены.
• echo (логический): Определяет, следует ли выводить результат на экран (true) или возвращать его для обработки (false). По умолчанию true.
• authors (строка): Показывает страницы только от указанных авторов. Указываются ID авторов, разделенные запятыми. По умолчанию пусто.
• sort_column (строка): Определяет поле для сортировки списка. Возможные значения:
  • post_title: Сортировка по заголовкам (по алфавиту).
  • menu_order: Сортировка по порядковому номеру.
  • post_date: Сортировка по дате создания.
  • post_modified: Сортировка по дате изменения.
  • ID: Сортировка по идентификатору записи.
  • post_author: Сортировка по ID авторов.
  • post_name: Сортировка по альтернативному имени поста. По умолчанию: menu_order, post_title.
• sort_order (строка): Определяет направление сортировки:
  • ASC: По возрастанию.
  • DESC: По убыванию. По умолчанию ASC.
• link_before (строка): Указывает текст или HTML-код, который будет вставлен перед текстом ссылки внутри тега <a>. По умолчанию пусто.
• link_after (строка): Указывает текст или HTML-код, который будет вставлен после текста ссылки внутри тега <a>. По умолчанию пусто.
• meta_key (строка): Фильтрует страницы по указанным произвольным полям. Работает только вместе с параметром meta_value. По умолчанию пусто.
• meta_value (строка): Фильтрует страницы по значениям произвольных полей. Ключ произвольного поля указывается в параметре meta_key. По умолчанию пусто.
• number (число): Ограничивает количество ссылок в списке. Значение 0 означает отсутствие ограничений. В некоторых случаях может не работать.
• offset (число): Пропускает указанное количество страниц в начале списка. Например, 5 пропустит первые 5 страниц. Добавлен в версии 2.8. По умолчанию 0.
• item_spacing (строка): Управляет переносами строк в HTML-коде меню. Значения: preserve или discard. По умолчанию preserve.
• walker (строка): Позволяет использовать пользовательский класс для построения списка. По умолчанию пусто.

Возвращает:

Строку с HTML-кодом списка страниц или null, если список пуст.

Шаблон:

wp_list_pages( [
	'authors'      => '',
	'child_of'     => 0,
	'date_format'  => get_option('date_format'),
	'depth'        => 0,
	'echo'         => 1,
	'exclude'      => '',
	'exclude_tree' => '',
	'include'      => '',
	'link_after'   => '',
	'link_before'  => '',
	'meta_key'     => '',
	'meta_value'   => '',
	'number'       => '',
	'offset'       => '',
	'post_type'    => 'page', // см. get_pages()
	'show_date'    => '',
	'sort_column'  => 'menu_order, post_title',
	'sort_order'   => 'ASC',
	'title_li'     => __('Pages'),
	'walker'       => '',
] );

Примеры:

Удаление заголовка списка:

<ul>
    <?php wp_list_pages('title_li='); ?>
</ul>

Изменение заголовка:

<ul>
    <?php wp_list_pages('include=4,5,7&title_li=<h2>' . __('Poetry') . '</h2>'); ?>
</ul>

Сортировка по порядковому номеру:

<ul>
    <?php wp_list_pages('sort_column=menu_order'); ?>
</ul>

Сортировка по дате создания:

<ul>
    <?php wp_list_pages('sort_column=post_date&show_date=created'); ?>
</ul>

Исключение страниц по ID:

<ul>
    <?php wp_list_pages('exclude=19,52'); ?>
</ul>

Список страниц с указанными ID:

<ul>
    <?php wp_list_pages('include=3,12,17,33&title_li=<h2>' . __('Pages') . '</h2>'); ?>
</ul>

Вывод дочерних страниц текущей страницы:

<?php
$children = wp_list_pages('title_li=&child_of=' . $post->ID . '&echo=0');
if ($children) {
    echo '<ul>' . $children . '</ul>';
}
?>

Статичный список дочерних страниц

<?php
if ($post->post_parent) {
    $children = wp_list_pages("title_li=&child_of=" . $post->post_parent . "&echo=0");
} else {
    $children = wp_list_pages("title_li=&child_of=" . $post->ID . "&echo=0");
}
if ($children) {
    echo '<ul>' . $children . '</ul>';
}
?>

Дерево дочерних страниц указанной страницы

<?php
$pages = get_pages('child_of=93');
$parent = 25;
if ($pages) {
    $pageids = array();
    foreach ($pages as $page) {
        $pageids[] = $page->ID;
    }
    wp_list_pages([
        'title_li' => 'Дерево родительской страницы: ' . $parent,
        'include'  => $parent . ',' . implode(',', $pageids),
    ]);
}
?>

Маркировка и стилизация списков

.pagenav {
    /* стили для основного списка */
}
.page-item-2 {
    /* стили для элемента с ID 2 */
}
.current_page_item {
    /* стили для текущей страницы */
}
.current_page_parent {
    /* стили для родительской страницы текущей */
}
.current_page_ancestor {
    /* стили для любой страницы, связанной с текущей */
}

Заключение

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