wordpress常用函数详解：wp_list_pages()

WordPress

wp_list_pages()函数的功能是以页面名称的超链接形式显示WordPress博客内的所有页面。wp_list_pages()函数在WordPress还没有出现自定义菜单功能的时候，常使用该函数做网站导航使用，大多用来修饰侧边栏。

wp_list_pages()函数语法结构：

wp_list_pages(’title_li=&sort_column=menu_order&include=12,25,38,57&depth=1& ’);

wp_list_pages()函数各参数意义如下：

  • title_li=：用来设置所有显示页面的一个总名称；后面没有参数值时，表示不显示名称；默认值为“_（’页面’）”，显示结果为“页面”。
  • sort_column=menu_order：表示按照WP后台设置的各页面顺序显示，post_title按标题字母顺序排序（默认）、post_date、ID、post_modified按最后修改时间、post_author按页面创建者排序等等；
  • include=12,25,38,57：表示只显示ID为这四个数值的四个页面；同样，也可以使用exclude来排除相应ID的页面；
  • depth=1：表示只显示父页面，对所有子页面不予显示；其他数值还包括默认的0，表示显示所 有页面（子页面有缩进）；-1显示所有页面（子页面无缩进）；2 表示需要显示页面内部的层级数;
  • ort_order：更改页面列表的排列顺序（升序或降序）。默认为升序‘asc’、‘desc’。
  • child_of ：仅显示单个页面的子页面；值为默认编号。默认值为0（显示所有页面）。注意child_of参数不仅获取直系子页面，也会从已知编号中获取“孙页面”。默认值为0（显示所有页面）。
  • show_data：在每篇页面旁显示创建日期或最新修改日期。默认值为空值（不显示日期）。可用的值包括：' '不显示日期（默认）、‘modified’ 显示最新修改日期。
  • date_format：该参数对show_date参数生成的页面日期格式（”l, F j, Y”）进行设置。默认格式为WordPress选项设定的日期格式。参见日期和时间设置以及php网站上的页面日期格式。
  • echo：触发显示所生成的链接列表，或将列表按HTML文本格式返回供PHP使用。默认值为1（显示生成的列表项）。可能的值包括：1 (true) 、0（false）。
  • hierarchical：在上级页面列表下以缩进方式显示下级页面。默认值为true（在父级列表项下显示其子页面）。可能的值有：1（true）、0（false）。
  • meta_key：仅包含含有该自定义字段关键字的页面（与meta_value字段联合使用）。
  • meta_value：仅包含含有该自定义字段值的页面（与meta_key字段联合使用）。

以上来自：http://wanlimm.com/77201403131434.html

2017年9月23日09:19:35更新：来自新浪博客的介绍

用法：

<?php wp_list_pages('arguments'); ?>

默认参数设置为：

$defaults = array(
 'depth' => 0, 显示所有页面和子页面（无深度限制）
 'show_date' => '', 不显示创建日期
 'date_format' => get_option('date_format'),
 'child_of' => 0, 子页面无限制
 'exclude' => '', 不删除任何页面
 'title_li' => __('Pages'), 页面列表的标题为“Pages（页面）”
 'echo' => 1, 回显（显示）结果
 'authors' => '', 不局限于特定作者
 'sort_column' => 'menu_order, post_title', 先按页面顺序再按页面标题排序
 'link_before' => '',
 'link_after' => '',
 'exclude_tree'=> '' );不删除父级/子级树

隐藏或改变列表标题

给title_li参数传递一个零值或空值，可以隐藏由wp_list_pages生成的页面列表默认标题。下面的代码可显示所述效果：

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

在下面这个例子中，列表中只包含编号为9，5，23的页面，标题内容被改为“Poetry”，格式为< h2 >:

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

将页面按页面顺序排列

下面的例子将页面按管理栏中 Write > Page 定义的页面顺序进行排列。

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

如果希望将列表按页面顺序进行排列并将“Prose”作为列表标题（以h2格式）显示在侧边栏中，可将以下代码添加到sidebar.php文件中：

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

使用下列代码段，可显示出无标题并以页面顺序排列的页面：

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

将页面按发表日期排列

下列代码显示出的页面将按发表日期进行排列，在页面列表项旁显示日期。

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

从列表中排除页面

用exclude参数可隐藏列表中由wp_list_pages生成的若干页面。

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

显示列表中特定页面

若仅希望在列表中显示特定页面，例如编号为35，7，26和13的页面，可使用include参数。

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

显示子页面

注意：即使没有子页面，HTML标签也是必要的（ul或ol）。用css设置列表时需要将这一点谨记在心。

<ul>
 <?php
 wp_list_pages('title_li=&child_of='.$post->ID.'&show_date=modified
 &date_format=$date_format'); ?>
 </ul>

以下代码仅在目前页面有子页面（将目前页面设为父级页面的页面）的情况下生成列表：

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

在子页面上列出子页面

上述示例都是在父级页面上展示子页面，却没有说明如何在子页面上进行展示。可用下列代码在某一父页面或其中一个子页面上展示子页面。

将本代码放在侧边栏的widget区块后，代码将无法运行。

<?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 } ?>

本代码也可用在sidebar.php中，仅显示顶级页面。但浏览到包含子页面的页面时，仅显示其子页面。

  • 浏览主页时在侧边栏显示所有顶级页面
  • 浏览没有子页面的顶级页面时，显示所有顶级页面
  • 浏览有子页面的顶级页面时，显示所有子页面及下一级页面
  • 浏览子页面时，显示其父级页面下的所有子页面和下一级页面
<?php
 $output = wp_list_pages('echo=0&depth=1&title_li=<h2>Top Level Pages </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;
 ?>

页面选项标记与格式

默认情况下，wp_list_pages( )生成一个嵌套的、由管理栏 Write > Page 生成的无序WordPress页面列表。将title_li参数设为任意空字符后可除去最外围选项（li.pagenav）和列表（ul）。

所有wp_list_pages( )生成的列表项（li）都被标上page_item类。显示页面时将调用wp_list_pages( )，这时该页面的列表项被赋予附加类current_page_item。

<?php
 <li class="pagenav">
 Pages [title_li]
 <ul>
 <!-- Output starts here if 'title_li' parameter is empty -->
 <li class="page-item-2 page_item current_page_ancestor current_page_parent">
 [parent of the current Page]
 <ul>
 <li class="page-item-21 page_item current_page_item">
 [the current Page]
 </li>
 </ul>
 </li>
 <li class="page-item-3 page_item">
 [another Page]
 </li>
 </ul>
 </li>

可以用CSS选择器为这些列表项进行样式设计：

.pagenav { … } /* the outermost list item; contains whole list */
 .page-item-2 { … } /* item for Page ID 2 */
 .page_item { … } /* any Page item */
 .current_page_item { … } /* the current Page */
 .current_page_parent { … } /* parent of the current Page */
 .current_page_ancestor { … } /* any ancestor of the current Page */ 参数
 sort_column (字符)
 按不同方式对页面列表进行排序。默认设置成按页面标题的字母顺序排序。

‘post_title’ —— 按页面标题的字母顺序排序——默认
 ‘menu_order’ —— 按页面顺序（Page Order）进行排序。注意页面顺序和页面编号的区别。页面编号是由WordPress为每篇文章或页面设定的独有的数字，而页面顺序则由用户在管理栏的Write>Pages中设置。
 ‘post_date’ —— 按页面创建日期排序。
 ‘post_modified’ —— 按最后修改时间进行排序。
 ‘ID’ —— 按页面序列编号排序。
 ‘post_author’ —— 按页面创建者的序列编号排序。
 ‘post_name’ —— 按页面缩略名的字母顺序排序。

注意：sort_column参数可按WordPress数据库 wp_post table中任意字段的描述符来对页面列表进行排序。下面给出一些实用示例。

sort_order (字符)

更改页面列表的排列顺序（升序或降序）。默认为升序。可能的值为：

  • ‘asc’ ——按从低到高顺序排列（默认）
  • ‘desc’ —— 按从高到低顺序排列
  • exclude (字符)

定义一列页面编号并用逗号隔开，将其从已有列表中删除（例如：’exclude=3，7，1′）。无默认值。

exclude_tree (整数)

与’child_of’相反，’exclude_tree’从结果中移除已知编号的所有子页面。也可用于隐藏已知页面的所有子页面。该参数还可联合’child_of’ 的值以隐藏孙页面。在2.7版本中该参数可用。

include (字符)

仅包含get_pages生成的特定页面列表。include参数与exclude同样用逗号将页面编号隔开。无默认值。

depth(整数)

该参数决定wp_list_pages生成的列表中包含的页面层次级数。默认值为0（显示子页面内的所有页面）。

  • 0 — 以层级方式（缩进）显示所有页面和子页面（默认）
  • -1 — 以平级方式（不缩进）显示子页面中的页面
  • 1 — 仅显示最上层页面
  • 2 — 该值（或更大值）表示需要显示页面内部的层级数

child_of (整数)

仅显示单个页面的子页面；值为默认编号。默认值为0（显示所有页面）。注意child_of参数不仅获取直系子页面，也会从已知编号中获取“孙页面”。默认值为0（显示所有页面）。

show_data(字符)

在每篇页面旁显示创建日期或最新修改日期。默认值为空值（不显示日期）。可用的值包括：

  • ‘ ‘ — 不显示日期（默认）
  • ‘modified’ — 显示最新修改日期
  • ‘xxx’ — 任何非’modified’值都将显示页面最初创建的日期（post_date）。参看上文中的示例。

date_format(字符)

该参数对show_date参数生成的页面日期格式（”l, F j, Y”）进行设置。默认格式为WordPress选项设定的日期格式。参见日期和时间设置以及php网站上的页面日期格式。

title_li (字符)

设置页面列表标题的内容与样式。默认值为“_（’页面’）”，显示结果为“页面”（_(”)用于本地定位）。若传递值为零或为空（”），则不显示标题，列表也不会被ul标签围绕。参见标题示例。

echo (布尔型)

触发显示所生成的链接列表，或将列表按HTML文本格式返回供PHP使用。默认值为1（显示生成的列表项）。可能的值包括：

  • 1 (true) — 默认
  • 0（false）

hierarchical（布尔型）

在上级页面列表下以缩进方式显示下级页面。默认值为true（在父级列表项下显示其子页面）。可能的值有：

  • 1（true）——默认
  • 0（false）

meta_key（字符）

仅包含含有该自定义字段关键字的页面（与meta_value字段联合使用）。

meta_value（字符）

仅包含含有该自定义字段值的页面（与meta_key字段联合使用）。

link_before（字符）

设置标签< a>中文字链接前的文本或html代码。（适用于2.7.0或更新版本）