描述
另见
参数
- $args
-
(array|string) (可选) 用于生成页面列表的参数数组或字符串。有关其他参数,请参阅
get_pages()
。- 'child_of'
(int) 只按ID显示单个页面的子页面。默认为0(所有页面) - 'authors'
(string) 以逗号分隔的作者ID列表。默认为空(所有作者) - 'date_format'
(string) 用于列出页面的PHP日期格式。依赖于'show_date'参数。默认是'date_format'选项的值。 - 'depth'
(int) 生成的列表中包含的页面层次数量。接受-1(任何深度),0(所有页面),1(仅顶级页面),和n(页面到指定的n深度)。默认为0。 - 'echo'
(bool) 是否输出列表,默认为true。 - 'exclude'
(string) 以逗号分隔的要排除的页面ID的列表。 - 'include'
(array) 以逗号分隔的要包含的页面ID的列表。 - 'link_after'
(string) 页面链接标签之后的文本或HTML。默认为null。 - 'link_before'
(string) 页面链接标签之前的文本或HTML。默认为null。 - 'post_type'
(string) 要查询的文章类型。默认为 "page"。 - 'post_status'
(string|array) 要包含的文章状态,逗号分隔的列表或数组。默认为 "publish"。 - 'show_date'
(string) 是否显示每个页面的发布或修改日期。接受 "modified" 或任何其他值。空值则隐藏日期。 - 'sort_column'
(string) 以逗号分隔的列名,用于对页面进行排序。接受'post_author', 'post_date', 'post_title', 'post_name', 'post_modified', 'post_modified_gmt', 'menu_order', 'post_parent', 'ID', 'rand', 或 'comment_count'。默认为'post_title'。 - 'title_li'
(string) 列表标题。传递null或空值将导致没有标题,而且列表不会被无序列表<ul>
标签包裹。默认 'Pages'。 - 'item_spacing'
(string) 是否在菜单的HTML中保留空白。接受 "preserve" 或 "discard"。默认为 "preserve"。 - 'walker'
(Walker) 用于列表页的 Walker 实例。默认为空,这将导致使用 Walker_Page 实例。
默认值: ''
- 'child_of'
返回
(void|string) 如果'echo'参数为true,则无返回,如果'echo'为false,则返回页面HTML列表。
说明
菜单项的CSS类
以下类应用于菜单项,即应用于由wp_list_pages()生成的HTML <li> 标签。注: wp_list_pages() 和 wp_page_menu() 函数输出相同的CSS类名。
所有菜单项
- .page_item
这个类被添加到对应于静态页面的菜单项中。 - .page-item-$ID
这个类被添加到对应于静态页面的菜单项中,其中$ID是静态页面的ID。
当前页的菜单项
- .current_page_item
这个类被添加到对应于当前渲染的静态页面的菜单项。
当前页的父级菜单项
- .current_page_parent
这个类被添加到对应于当前渲染的静态页面的分层父级菜单项中。
当前页的祖先菜单项
- .current_page_ancestor
这个类被添加到对应于当前渲染的静态页面的分层祖先的菜单项。
源码
更新日志
版本 | 描述 |
---|---|
4.7.0 | 添加了item_spacing 参数 |
1.5.0 | 开始引入 |
使用示例
列出WordPress 2.0.1之前的子页面:
把它放在WordPress主题的
page.php
模板的the_post()
部分的the_content()
后面,或把它放在page.php模板的副本中,用于有子页的页面:<ul> <?php global $id; wp_list_pages( array( 'title_li' => '', 'child_of' => $id, 'show_date' => 'modified', 'date_format' => $date_format ) ); ?> </ul>
如果放置在页面模板中,此示例不适用于WordPress 2.0.1或更新版本,因为未设置全局
$id
。请使用以下代码。WordPress 2.0.1或更新版本:
注意:即使没有子页面,也需要HTML列表标签 (
<ul>
或<ol>
) 。如果您使用CSS设置列表样式,请记住这一点。<ul> <?php wp_list_pages( array( '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 endif; ?>
隐藏或更改列表标题可以通过为
title_li
参数传递null或空值来隐藏由wp_list_pages
生成的页面列表(“页面”)的默认标题。以下示例在列表上方不显示标题文本。<ul> <?php wp_list_pages( array( 'title_li' => '' ) ); ?> </ul>
在以下示例中,列表中仅包括ID为9、5和23的页面,标题文本已更改为单词“Poetry”,标题样式为:
<ul> <?php wp_list_pages( array( 'include' => array( 5, 9, 23 ), 'title_li' => '<h2>' . __('Poetry') . '</h2>' ) ); ?> </ul>
如果给定的自定义文章类型本质上是分层的,则可以使用
wp_list_pages()
列出该自定义文章类型的成员。在本例中,列出了自定义文章类型 Portfolio:$args = array( 'post_type' => 'portfolio', 'title_li' => __( 'Portfolio', 'textdomain' ) ); wp_list_pages( $args );
我没有看到任何地方可以传递sort_order参数。因此,我认为最好将其包含在args列表中,使其更加明显。
这段代码按post_date对页面进行排序,并按降序对页面进行排序,以便首先获得最新的页面。
wp_list_pages(array('sort_column' => 'post_date', 'sort_order' => 'desc'));
列出子页面,即使在子页面上
以上示例仅显示父页面中的子页面,而不是实际位于子页面上的子页面。当在父页面或其中一个子页面上时,此代码将显示子页面,并且仅显示子页面。
如果将此代码放在边栏中的小工具块之后,则该代码将不起作用。
<?php if ( $post->post_parent ) { $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $post->post_parent, 'echo' => 0 ) ); } else { $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $post->ID, 'echo' => 0 ) ); } if ( $children ) : ?> <ul> <?php echo $children; ?> </ul> <?php endif; ?>
另一种选择是,在
sidebar.php
中的这段代码只显示顶级页面,但当查看具有子级(或是子级)的页面时,它只显示该父级的子级。当访问主页时,所有顶级页面都列在侧边栏中
当访问没有子级的顶级页面时,会列出所有顶级页面
当访问包含子页面的顶级页面时,只列出子页面和后代页面
当访问子页面时,只列出该父页面的子页面和后代页面。<?php if ( $post->post_parent ) { $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $post->post_parent, 'echo' => 0 ) ); } else { $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $post->ID, 'echo' => 0 ) ); } if ( $children ) : ?> <ul> <?php echo $children; ?> </ul> <?php endif; ?>
仅当存在子页面时才显示的页面列表,在父页面和子页面上显示子页面的页面列表,但此代码将父页面名称保留在标题中,这与上一示例不同。
<?php if ( $post->post_parent ) { $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $post->post_parent, 'echo' => 0 ) ); } else { $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $post->ID, 'echo' => 0 ) ); } if ( $children ) : ?> <ul> <?php echo $children; ?> </ul> <?php endif; ?>
页面项目的标记和样式
默认情况下,wp_list_pages()
会生成一个嵌套的、无序的WordPress页面列表,这些页面是用Write > Page管理面板创建的。通过将title_li
参数设置为空字符串,可以删除最外层的项(li.pagenav
)和列表(ul
)。wp_list_pages()
生成的所有列表项(li
)都用类page_item
标记。当显示页面时调用wp_list_pages()
时,该页面的列表项被赋予额外的类current_page_item
。<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选择器设置样式:
<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>
从列表中排除页面
使用exclude
参数从要由wp_list_pages
生成的列表中隐藏某些页面。<ul> <?php wp_list_pages( 'exclude=17,38' ); ?> </ul>
仅列出此父级的所有顶级页面和子页面
以下列出了所有顶级页面和
如果在顶级页面上–仅此页面的子页面
如果在子页面上–其同级页面,但不包括其他顶级页面的子页面$ancestor_id = 1843; // you want to change this $descendants = get_pages( array( 'child_of' => $ancestor_id ) ); $incl = ''; foreach ( $descendants as $page ) { if ( ( $page->post_parent == $ancestor_id ) || ( $page->post_parent == $post->post_parent ) || ( $page->post_parent == $post->ID ) ) { $incl .= $page->ID . ","; } } ?> <ul> <?php wp_list_pages( array( 'child_of' => $ancestor_id, 'include' => $incl, 'link_before' => '', 'title_li' => '', 'sort_column' => 'menu_order' ) ); ?> </ul>
按页面顺序列出页面
下面的例子是按照 "页面→编辑" 面板中各页的排序设置所定义的顺序列出各页。<ul> <?php wp_list_pages( array( 'sort_column' => 'menu_order' ) ); ?> </ul>
如果您想按页面顺序对列表进行排序,并在侧栏上显示单词“Prose”作为列表标题(h2样式),您可以在侧栏中添加以下代码。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>
在列表中包含页面
要仅包括列表中的某些页面,例如ID号为35、7、26和13的页面,请使用include
参数。<ul> <?php wp_list_pages( 'include=7,13,26,35&title_li=<h2>' . __( 'Pages' ) . '</h2>' ); ?> </ul>
列出整个子页面
这是如何获得整个子页面列表
if( ! $post->post_parent ) { // Will display the subpages of this top level page. $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $post->ID, 'echo' => 0 ) ); } else { if ( $post->ancestors ) { /* * Now you can get the the top ID of this page. WordPress is putting the ids DESC, * thats why the top level ID is the last one. */ $ancestors = get_post_ancestors( $this_page ); $children = wp_list_pages( array( 'title_li' => '', 'child_of' => $ancestors, 'echo' => 0 ) ); } } if ( $children ) : ?> <ul> <?php echo $children; ?> </ul> <?php endif; ?>
列出父页面和所有子页面
由于无法告诉
wp_list_pages
显示特定的父级(父代和所有代显示),因此本例使用get_pages
获取父代的所有子代,然后使用wp_list_pages
显示其所有父、子级页面。<?php // Use wp_list_pages to display parent and all child pages all generations (a tree with parent). $parent = 93; $args = array( 'child_of' => $parent ); $pages = get_pages( $args ); if ( $pages ) { $pageids = array(); foreach ( $pages as $page ) { $pageids[] = $page->ID; } $args = array( 'title_li' => sprintf( __( 'Tree of Parent Page %s', 'textdomain' ), $parent ), 'include' => $parent . ',' . implode( ",", $pageids ) ); wp_list_pages( $args ); } ?>
列出当前页面及其祖先和子页面
本例将列出当前页面、当前页面的祖先和当前页面的子项,因为
child_of
显示所有子项,所以使用wpdb
以及include来代替,以不显示所有内容。// If the post has a parent. if( $post->post_parent ) { // Collect ancestor pages. $relations = get_post_ancestors( $post->ID ); // Get child pages. $result = $wpdb->get_results( $wpdb->prepare( "SELECT ID FROM wp_posts WHERE post_parent = %s AND post_type = %s", $post->ID, 'page' ) ); if ( $result ) { foreach ( $result as $page ) { array_push( $relations, $page->ID ); } } // Add current post to pages. array_push( $relations, $post->ID ); // Get comma delimited list of children and parents and self. $relations_string = implode( ",",$relations ); // Use include to list only the collected pages. $sidelinks = wp_list_pages( array( 'title_li' => '', 'echo' => 0, 'include' => $relations_string ) ); } else { // Display only main level and children. $sidelinks = wp_list_pages( array( 'title_li' => '', 'echo' => 0, 'depth' => 1, 'child_of' => $post->ID ) ); } if ( $sidelinks ) : ?> <h2><?php the_title(); ?></h2> <ul> <?php // Links in <li> tags. echo $sidelinks; ?> </ul> <?php endif; ?>
列出最顶端的祖先及其直系子代
此方法将显示当前页面的最顶层祖先以及最顶层祖先的直接子级。这可用于清洁次级导航。
首先,创建以下函数(最好在
functions.php
中),假设这是一个主题:if ( ! function_exists( 'wpdocs_get_post_top_ancestor_id' ) ) { /** * Gets the id of the topmost ancestor of the current page. * * Returns the current page's id if there is no parent. * * @return int ID of the top ancestor page. */ function wpdocs_get_post_top_ancestor_id() { if ( ! $post = get_post() ) { return; } $top_ancestor = $post->ID; if ( $post->post_parent ) { $ancestors = array_reverse( get_post_ancestors( $post->ID ) ); $top_ancestor = $ancestors[0]; } return $top_ancestor; } } // Exists.
接下来,将以下代码添加到主题中(无论您希望菜单出现在哪里):
if ( ! function_exists( 'wpdocs_get_post_top_ancestor_id' ) ) { /** * Gets the id of the topmost ancestor of the current page. * * Returns the current page's id if there is no parent. * * @return int ID of the top ancestor page. */ function wpdocs_get_post_top_ancestor_id() { if ( ! $post = get_post() ) { return; } $top_ancestor = $post->ID; if ( $post->post_parent ) { $ancestors = array_reverse( get_post_ancestors( $post->ID ) ); $top_ancestor = $ancestors[0]; } return $top_ancestor; } } // Exists.