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

相关函数：

• wp_page_menu()
• wp_dropdown_pages()