WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

wp_list_pages() WP 1.5

Выводит список постоянных страниц в виде ссылок.

Обычно используется в файлах header.php (шапка сайта) или sidebar.php (боковая панель) для создания меню.

Смотрите также очень похожую функцию wp_page_menu();

Альтернативой для создания меню является функция wp_nav_menu(), добавлена с версии 3.0. Мануал читайте здесь.

Является основой для: wp_page_menu()
Работает на основе: get_pages()
✈ 1 раз = 0.014449с = тормоз | 50000 раз = 213.16с = тормоз | PHP 7.1.2, WP 4.7.3
Хуки из функции

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

<?php wp_list_pages( $args ); ?>

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

$args = array(
	'depth'        => 0,
	'show_date'    => '',
	'date_format'  => get_option('date_format'),
	'child_of'     => 0,
	'exclude'      => '',
	'exclude_tree' => '',
	'include'      => '',
	'title_li'     => __('Pages'),
	'echo'         => 1,
	'authors'      => '',
	'sort_column'  => 'menu_order, post_title',
	'sort_order'   => 'ASC',
	'link_before'  => '',
	'link_after'   => '',
	'meta_key'     => '',
	'meta_value'   => '',
	'number'       => '',
	'offset'       => '',
	'walker'       => '',
	'post_type'    => 'page', // из функции get_pages()
); 

wp_list_pages( $args );

Кроме параметров ниже, функция может принимать все те же параметры что и get_pages(), потому что она работает на её основе.

depth(число)

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

  • 0 (по умолчанию) Включать в список все уровни вложенных страницы и показывать их в древовидном виде.
  • -1 Включить в список все уровни вложенных страниц, но не показывать вложенность (древовидное отображение списка отключается, список будет показан как общий).
  • 1 Показать только первые вложенные страницы, т.е. дочерние страницы первого уровня.
  • 2, 3 и т.д. Включить в список дочерние страницы 2, 3 и т.д. уровня…

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

show_date(строка)

Показывает дату создания или изменения страницы, рядом со ссылкой. По умолчанию показ дат отключен.

  • '' - не показывать даты (по умолчанию).
  • modified - показывать дату изменения.
  • created - показывать дату создания страницы.

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

date_format(строка)
Контролирует в каком виде будет показана дата, если включен параметр show_date, например, d/m/Y выведет: 10/11/2011
По умолчанию: настройки даты в WordPress
child_of(число)
Показывать только дочерние страницы отдельной страницы, указанной в этом параметре. Указывать нужно ID страницы, подстраницы которой мы хотим вывести. По умолчанию 0 - показывать все страницы.
По умолчанию: 0
exclude(строка)
В этом параметре указываем через запятую ID тех страниц, которые мы не хотим, чтобы попали в список, например: exclude=3,7,31.
По умолчанию: ''
exclude_tree(строка)
Укажите через запятую ID родительский страниц, которые вы хотите исключить из списка. Так же будут исключены все вложенные (дочерние страницы) указанных ID. Т.е. этот параметр исключает из списка все дерево страниц.
Добавлен в версии 2.7.
По умолчанию: ''
include(строка/массив)

Показать в списке только указанные страницы. ID можно указать через запятую или пробел в виде строки: include=45 63 78 94 128 140.

Этот параметр отменяет параметры относящиеся к формированию списка, так как он создает список только из тех страниц которые указаны. Отменяются параметры: exclude, child_of, depth, meta_key, meta_value, authors.
По умолчанию: ''

title_li(строка)
Заголовок списка. По умолчанию: __('Pages') __('') нужно для локализации. Если обнулить этот параметр (''), то заголовок списка не будет показываться, так же будут удалены HTML теги обрамляющие список (<ul>, </ul>).
По умолчанию: __('Pages')
echo(логический)
Выводить результат на экран (true) или возвращать для обработки (false).
По умолчанию: true
authors(строка)
Показать страницы принадлежащие только указанным в этом параметре авторам. Указывать нужно ID авторов, через запятую.
По умолчанию: ''
sort_column(строка)

Сортировать список по указанным полям. По умолчанию список сортируется по заголовкам (post_title), в алфавитном порядке. Можно указывать несколько параметров через запятую, в соответствии с которыми потом будет отсортирован список.

  • post_title - сортировать по заголовку (в алфавитном порядке);
  • menu_order - сортировать по порядку, который указывается на админ-панели на странице редактирования "постоянной страницы";
  • post_date - сортировать по дате создания "постоянной страницы";
  • post_modified - сортировать по дате изменения страницы;
  • ID - сортировать по идентификатору записи в Базе Данных (по ID);
  • post_author - сортировать по ID авторов;
  • post_name - сортировать в алфавитом порядке по альтернативному имени поста (обычно транслитерация заголовка).

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

sort_order(строка)
Направление сортировки: 'ASC' - по порядку, 'DESC' - в обратном порядке.
По умолчанию: 'ASC'
link_before(строка)
Укажите здесь текст или HTML код, который будет вставлен перед текстом ссылки (внутри тега <a>). Добавлен в версии 2.7.
По умолчанию: ""
link_after(строка)
Укажите здесь текст или HTML код, который будет вставлен после текста ссылки (внутри тега <a>). Добавлен в версии 2.7.
По умолчанию: ""
meta_key(строка)
Выведет страницы, имеющие только указанные произвольные поля (работает только вместе с параметром meta_value).
По умолчанию: ''
meta_value(строка)
Выведет страницы, имеющие только указанные значения произвольных полей (ключ произвольного поля указывать обязательно в параметре meta_key).
По умолчанию: ''
number(число)
Ограничение количества ссылок в списке (SQL LIMIT). В некоторых случаях может не работать.
По умолчанию: нет
offset(число)
Верхний отступ списка. Например, если указать 5, то первые 5 ссылок, которые должны были бы быть показаны не будет показаны в списке.
Добавлен в версии 2.8.
По умолчанию: нет
item_spacing(строка)
Оставлять или нет переносы строк в HTML коде меню. Может быть: preserve или discard. C WP 4.7.
По умолчанию: 'preserve'
walker(строка)
php Класс, который обрабатывает построение списка.
По умолчанию: ''

Примеры

#1 Удаление или изменение заголовка списка

#1.1 Удалим заголовок списка, отменив параметр title_li.

Имейте ввиду, что теги ul так же будет удалены и их нужно указывать отдельно:

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

#1.2. Изменим заголовок

Изменим заголовок на "Поэты", обвернем его в HTML тег <h2> и выведем в списке только постоянные страницы с ID 9, 5 и 23:

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

#2 Сортировка списка страниц

#2.1 Отсортируем список в соответствии с порядковыми номерами, указанными на странице редактирования "постоянных страниц":

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

#2.2 Используя этот код, мы уберем заголовок "Страницы" у списка:

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

#2.3 Теперь выведем список отсортированный по дате создания "постоянной страницы" и покажем дату рядом с каждой ссылкой:

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

#3 Исключение и включение страниц

#3.1 Используя параметр exclude исключим страницы с ID 17,38:

<ul>
	<?php wp_list_pages('exclude=17,38' ); ?>
</ul>

#3.2 Используя параметр include, создадим список только из страниц в ID 35, 7, 26 и 13:

<ul>
	<?php wp_list_pages('include=7,13,26,35&title_li=<h2>' . __('Pages') . '</h2>' ); ?>
</ul>

#4 Вывод дочерних страниц

#4.1 Выведем список дочерних страниц 

Используя следующий пример, можно вывести в сайдбаре (или где-нибудь еще) список дочерних страниц (подстраниц), постоянной страницы на который вы сейчас находитесь. Для этого воспользуемся параметром child_of и проверкой существуют ли вообще дочерние страницы для текущей (попробуем получить дочерние страницы в переменную $children, если получится, выведем список):

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

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

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

<?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) { ?>
  <ul>
  <?php echo $children; ?>
  </ul>
<?php } ?>

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

меню

#4.3. Альтернативный вариант предыдущего кода. Этот пример также можно использовать в сайдбаре, он будет выводить:

  • когда вы находитесь на главной странице, будут показаны все "постоянные страницы" верхнего уровня;

  • когда вы находитесь на "постоянной странице" верхнего уровня, у которой нет дочерних страниц, будут показаны все те же "постоянные страницы" верхнего уровня;

  • когда вы находитесь на "постоянной странице" верхнего уровня, у которой есть дочерние страницы, будут показаны эти дочерние страницы и их дочерние страницы;

  • когда вы находитесь на дочерней странице "постоянной страницы" верхнего уровня (на странице второго уровня), будут показаны дочерние страницы "постоянной страницы" верхнего уровня (т.е. дочерние страницы родительской).
<?php
$output = wp_list_pages('echo=0&depth=1&title_li=<h2>Страницы верхнего уровня</h2>' );
if (is_page( )) {
  $page = $post->ID;
  if ($post->post_parent) {
	$page = $post->post_parent;
  }
  $children=wp_list_pages( 'echo=0&child_of=' . $page . '&title_li=' );
  if ($children) {
	$output = wp_list_pages ('echo=0&child_of=' . $page . '&title_li=<h2>Child Pages</h2>');
  }
}
echo $output;
?>
меню

#4.4 Список страниц, только если он есть

Список дочерних страниц, который будет показан, только если у "постоянной страницы" есть дочерние страницы. Дочерние страницы будут показаны как на родительской "постоянной странице" так и на самих дочерних страницах. Отличием от предыдущего примера, является наличие названия родительской "постоянной страницы" в заголовке списка:

<?php
  if($post->post_parent) {
  $children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");
  $titlenamer = get_the_title($post->post_parent);
  }

  else {
  $children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
  $titlenamer = get_the_title($post->ID);
  }
  if ($children) { ?>

  <h2> <?php echo $titlenamer; ?> </h2>
  <ul>
  <?php echo $children; ?>
  </ul>

<?php } ?>
меню

#4.5 Как получить все дочерние страницы, на "постоянных страницах" любого уровня вложенности:

<?php
if(!$post->post_parent){
	// получим дочерние страницы, для "постоянной страницы" верхнего уровня
	$children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
}else{
	// получим дочерние страницы, если мы находимся на дочерней странице первого уровня.
	//$children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");

	if($post->ancestors)
	{
		// теперь получим ID самой первой страницы (старшой)
		// wp собирает ID в обратном порядке, поэтому "первая" страницы будет последней
		$ancestors = end($post->ancestors);
		$children = wp_list_pages("title_li=&child_of=".$ancestors."&echo=0");
		// все, теперь у нас всегда будет список из всех дочерних страниц,
		// на каком уровне вложенности мы бы не находились.
	}
}

if ($children) { ?>
	<ul>
		<?php echo $children; ?>
	</ul>
<?php } ?>
меню

#4.6 Дерево дочерних страниц указанной "постоянной страницы"

Так как нет возможности указать wp_list_pages выводить дерево (все уровни вложенности) страниц определенной страницы (например, страницы с ID 93), то для такого трюка мы можем воспользоваться функцией get_pages():

<?php
// используем wp_list_pages, чтобы показать родительскую и все дочерние страницы (включая все вложенные в них)
$pages = get_pages("child_of=93");
if ($pages) {
  $pageids = array();
  foreach ($pages as $page)
	$pageids[]= $page->ID;

  $args=array(
	'title_li' => 'Дерево родительской страницы: ' . $parent,
	'include' =>  $parent . ',' . implode(",", $pageids)
  );
  wp_list_pages($args);
}
?>
меню

#5 Маркировка и Стилизация списков постоянных страниц

По умолчанию, wp_list_pages() создает список такой конструкции:

<li class="pagenav">Страницы
	<ul>
		<li class="page_item page-item-4"></li>
		<li class="page_item page-item-5"></li>
		...
	</ul>
</li>

Если мы уберем заголовок, поставив пустой параметр title_li=, то вид станет таким:

<li class="page_item page-item-4"></li>
<li class="page_item page-item-5"></li>
...

По-другому можно написать так:

<li class="pagenav">
Страницы [title_li]
  <ul>
	<!-- Список начинается от сюда, если параметр 'title_li' пустой -->
	<li class="page-item-2 page_item current_page_ancestor current_page_parent">
	  [родитель текущей страницы]
		  <ul>
			<li class="page-item-21 page_item current_page_item">[текущая страница]</li>
		  </ul>
	</li>
	<li class="page-item-3 page_item">[другие страницы]</li>
  </ul>
</li>

Все теги li создаваемые функцией wp_list_pages() помечены CSS классом page_item. Когда в списке появляется страница на который вы находитесь, к li элементу списка добавляется еще класс current_page_parent.

Таким образом, список можно "раскрашивать" следующими CSS селекторами:

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

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

.pagenav  ul ul,
.pagenav .current_page_item ul ul,
.pagenav .current_page_ancestor ul ul,
.pagenav .current_page_ancestor .current_page_item ul ul,
.pagenav .current_page_ancestor .current_page_ancestor ul ul {
	display: none;
}

.pagenav .current_page_item ul,
.pagenav .current_page_ancestor ul,
.pagenav .current_page_ancestor .current_page_item ul,
.pagenav .current_page_ancestor .current_page_ancestor ul,
.pagenav .current_page_ancestor .current_page_ancestor .current_page_item ul,
.pagenav .current_page_ancestor .current_page_ancestor .current_page_ancestor ul {
	display: block;
}
меню

#6. Список родственных или дочерних страниц к текущей

<?php
// если это дочерняя страница
if( $post->post_parent ){
	// собираем родственные страницы
	$relations = get_post_ancestors($post->ID);

	// получаем дочерние страницы (если есть)
	$result = $wpdb->get_results( "SELECT ID FROM wp_posts WHERE post_parent = $post->ID AND post_type='page'" );

	// если дочерние страницы этой страницы получилось
	// получить объединяем их с родственными
	if ($result){
		foreach($result as $pageID){
			array_push($relations, $pageID->ID);
	  }
	}

	// добавляем текущую страницу к родственным
	array_push($relations, $post->ID);

	// делаем список ID разделенный запятыми из родственных, дочерних и текущей
	$relations_string = implode(",",$relations);

	// получаем список с помощью параметра include
	$sidelinks = wp_list_pages("title_li=&echo=0&include=".$relations_string);
}
// если это не дочерняя страница
else {
	// показываем только дочерние страницы один уровень
	$sidelinks = wp_list_pages("title_li=&echo=0&depth=1&child_of=". $post->ID);
}

if( $sidelinks ){
	?>
	<h2><?php the_title() ;?></h2>
	<ul>
		<?php // выводим на экран ссылки в <li> тегах
		echo $sidelinks; ?>
	</ul>
	<?php
}
?>
меню

#7 Использование произвольного типа записей (отличного от page)

Если на сайте создан произвольный тип записей с древовидной структурой, то wp_list_pages() можно использовать для вывода и таких записей.

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

Тип записи указывается в параметре post_type:

wp_list_pages( array(
  'post_type'=>'portfolio',
  'title_li'=> __('Portfolio')
) );

Заметки

  • С версии 2.7 добавлены параметры: link_before, link_after и exclude_tree.
  • С версии 2.8 добавлены параметры: number и offset.

Хотите получить действительно живых подписчиков на канал в Телеграме, но не знаете где это сделать? Переходите по ссылке и покупайте необходимый ресурс по невероятно дешевым ценам. Также Вам будут доступны оптовые скидки для более быстрого и эффективного продвижения канала.

Код wp list pages: wp-includes/post-template.php WP 5.2.2

<?php
function wp_list_pages( $args = '' ) {
	$defaults = array(
		'depth'        => 0,
		'show_date'    => '',
		'date_format'  => get_option( 'date_format' ),
		'child_of'     => 0,
		'exclude'      => '',
		'title_li'     => __( 'Pages' ),
		'echo'         => 1,
		'authors'      => '',
		'sort_column'  => 'menu_order, post_title',
		'link_before'  => '',
		'link_after'   => '',
		'item_spacing' => 'preserve',
		'walker'       => '',
	);

	$r = wp_parse_args( $args, $defaults );

	if ( ! in_array( $r['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
		// invalid value, fall back to default.
		$r['item_spacing'] = $defaults['item_spacing'];
	}

	$output       = '';
	$current_page = 0;

	// sanitize, mostly to keep spaces out
	$r['exclude'] = preg_replace( '/[^0-9,]/', '', $r['exclude'] );

	// Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array)
	$exclude_array = ( $r['exclude'] ) ? explode( ',', $r['exclude'] ) : array();

	/**
	 * Filters the array of pages to exclude from the pages list.
	 *
	 * @since 2.1.0
	 *
	 * @param array $exclude_array An array of page IDs to exclude.
	 */
	$r['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) );

	// Query pages.
	$r['hierarchical'] = 0;
	$pages             = get_pages( $r );

	if ( ! empty( $pages ) ) {
		if ( $r['title_li'] ) {
			$output .= '<li class="pagenav">' . $r['title_li'] . '<ul>';
		}
		global $wp_query;
		if ( is_page() || is_attachment() || $wp_query->is_posts_page ) {
			$current_page = get_queried_object_id();
		} elseif ( is_singular() ) {
			$queried_object = get_queried_object();
			if ( is_post_type_hierarchical( $queried_object->post_type ) ) {
				$current_page = $queried_object->ID;
			}
		}

		$output .= walk_page_tree( $pages, $r['depth'], $current_page, $r );

		if ( $r['title_li'] ) {
			$output .= '</ul></li>';
		}
	}

	/**
	 * Filters the HTML output of the pages to list.
	 *
	 * @since 1.5.1
	 * @since 4.4.0 `$pages` added as arguments.
	 *
	 * @see wp_list_pages()
	 *
	 * @param string $output HTML output of the pages list.
	 * @param array  $r      An array of page-listing arguments.
	 * @param array  $pages  List of WP_Post objects returned by `get_pages()`
	 */
	$html = apply_filters( 'wp_list_pages', $output, $r, $pages );

	if ( $r['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}

Cвязанные функции

Из метки: Список (wp_list списки)

Еще из раздела: Страницы

25 комментов
Вопросы 1 Все
  • Лев cайт: smokedriver.ru

    А как можно вывести не только ссылку на страницу, но и некоторые другие данные (например, значения произвольных полей)?

    1
    Ответить7.5 лет назад #
  • @ максим cайт: www.famous-scientists.ru/11555

    здравствуйте. подскажите пожалуйста плагин для изменения ID страниц.

    Ответить7.4 лет назад #
  • @ Serg cайт: swt.org.ua

    У тебя вкралась ошибка\неточность\

    depth - 1 Показать только первые вложенные страницы, т.е. дочерние страницы первого уровня.

    Это же не дочерние, не вложенные. Это же только родительские страницы. Без дочерних.

    ЗЫ. А воще спасибо тебе за русские мануалы. Всегда использую твой сайт и всем показываю мануалы именно твои wink

    Ответить6.8 лет назад #
    • Kama7482

      Ну да, согласен - неточность. Спасибо, сейчас поправлю.

      Ответить6.8 лет назад #
      • @ Serg cайт: swt.org.ua

        Ещё не исправлено. Кеш наверное забыл почистить? wink

        Ответить6.8 лет назад #
  • Юрий

    Скажите пожалуйста, как соединить примеры 4,4 и 7. Тоесть, создал произвольный тип записи с иерархией страниц. Каким образом можно выводить список дочерних пользовательских типов записей (страниц), когда находишся в родительской, и на странице дочерней?

    Ответить6.6 лет назад #
  • Anton cайт: bronirovaniyeaviabiletov.blogspot.com

    Спасибо за содержательный пост. Отличная работа! Читал не отрываясь...

    Ответить6 лет назад #
  • Alicelf cайт: myskills.in.ua/portf

    Спс за перевод. На офиц сайте инфа та-же, но в Английском все-же плаваю, по-этому пригодилось.
    В закладки

    Ответить5.6 лет назад #
  • ganga

    Отличный мануал. Благодарствую good

    Ответить5.5 лет назад #
  • Владимир cайт: studio-promotion.com

    Это просто супер! Нижайший поклон за пост. Никак не мог сообразить, как оставить список дочерних страниц при переходе в подстраницы. Теперь все Ок.

    Ответить5.4 лет назад #
  • Виктор cайт: kybanskiy.ru

    Спасибо большое. Почти всегда нахожу нужную инфу по вп у вас.

    Ответить5 лет назад #
  • Denis Creative cайт: denis-creative.com

    Живу на этом сайте, здесь есть все, в очередной раз нужные части кода ищу здесьmosking Вывод дочерних страниц - отличный вариант для подменю, Спасибо!

    Ответить4.8 года назад #
    • Kama7482

      Рад, что сайт полезен, спасибо за позитивный комментарий gamer

      Ответить4.8 года назад #
Здравствуйте, !     Войти . Зарегистрироваться