WordPress页面列表标签:wp_list_pages

WordPress模板标签wp_list_pages用于输出页面列表,通常用在导航或企业模板的侧边栏。

wp_list_pages( array|string $args = '' )

函数参数

$args

数组或字符串值

wp_list_pages()函数$args参数默认的值如下:

$args = 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'	=> '',
	'walker'		=> '',
);

wp_list_pages()函数$args参数可用的值如下:

child_of

整数型,默认值:0

指定一个页面ID,将输出该页面的子页面,不包含该页面。

authors

字符串值,默认为空

作者ID,多个ID用逗号分隔,只有指定的作者发表的页面才被显示,默认显示所有作者发表的页面。

date_format

字符串值,默认为后台常规设置中的日期格式

当show_date的值不为空时,也就是显示页面发表或修改日期,date_format指定该日期的格式

depth

整数型,默认值:0

  • 0:输出所有的页面和子页面,按层级的方式输出;
  • 1:只输出顶级页面,不包含任何子页面;
  • n:根据n的具体数字来显示相应等级的页面;
  • -1:输出所有的页面和子页面,不以层级的方式输出;

echo

布尔值,默认值:1

是否输出结果,如果为0,只返回结果而不输出。

exclude

字符串值,默认为空

要排除的页面ID,多个ID用逗号分隔。

include

字符串值,默认为空

要显示的页面ID,多个ID用逗号分隔,默认显示所有页面。

link_after

字符串值,默认为空

追加字符到链接锚文本的后面,即</a>的前面。

link_before

字符串值,默认为空

追加字符到链接锚文本的前面,即紧跟<a>标记。

post_type

字符串值,默认值:page

文章类型,暂时没有发现用处

post_status

字符串值,默认值:publish

按页面的状态来显示,默认只显示已发表的页面

  • publish:已发表的页面
  • trash:回收站中的页面
  • private:私密
  • auto-draft:自动草稿
  • draft:草稿

show_date

字符串值,默认为空

传递任意值将显示页面的发表日期,显示的日期格式由date_format决定。

  • modified:显示页面的修改日期
  • 任意值:显示页面的发表日期,例如:created

sort_column

字符串值,默认值:menu_order, post_title

指定页面列表的排序方式,多个值用逗号分隔

  • post_author:按作者排序
  • post_date:按发表日期排序
  • post_title:按页面标题排序
  • post_name:按页面别名排序
  • post_modified:按修改日期排序
  • post_modified_gmt:按修改日期排序,与上面的post_modified不同之处在于这里是格林时间
  • menu_order:按页面设置中的“排序”
  • post_parent:按父页面排序
  • ID:按页面ID排序
  • rand:随机排序
  • comment_count:按评论数量排序

sort_order

字符串值,默认值:ASC

页面列表的排序顺序

  • ASC:升序排列;
  • DESC:降序排列;

title_li

字符串值,默认值:Pages

提供一个字符串作为页面列表的标题,不需要标题可以传递一个空值。

walker

用于列表页的实例,默认为空,参考Walker_Page

函数使用示例

排除ID为4、23的页面,显示发表日期并按发表日期的降序排列

<ul>
    <?php 
		$args = array(
			'show_date' => 'created',
			'sort_column' => 'post_date',
			'sort_order'=> 'DESC',
			'exclude' => '4,23',
		);
		wp_list_pages($args);
	?> 
</ul>

下面的代码输出同样的结果:

<ul>
	<?php wp_list_pages('show_date=created&sort_column=post_date&sort_order=DESC&exclude=4,23'); ?> 
</ul>

一个比较有用的例子,如果当前页面为子页面,则输出它的兄弟页面,否则输出顶级页面:

<?php
	if( $post->post_parent ) {
		$pages = wp_list_pages( array(
			'title_li' => '',
			'child_of' => $post->post_parent,
			'echo'     => 0
		) );
	} else {
		$pages = wp_list_pages( array(
			'title_li' => '',
			'echo' => 0,
			'depth' => 1,
		) );
	}
?>
<ul>
	<?php echo $pages; ?>
</ul>

扩展阅读

wp_list_pages()函数位于:wp-includes/post-template.php

相关函数:

Typora