当前浏览:首页 / WordPress函数 / wp_list_pages()

wp_list_pages( array|string $args = '' )

以(li)格式检索或显示页面列表 (或分层文章类型项)

listmore...

pagemore...


描述

另见


参数

$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 实例。

默认值: ''


返回

(void|string) 如果'echo'参数为true,则无返回,如果'echo'为false,则返回页面HTML列表。


说明

以下类应用于菜单项,即应用于由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开始引入

用户贡献的笔记

  • 贡献者:Codex

    列出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; ?>
    
  • 贡献者:Codex

    隐藏或更改列表标题可以通过为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>
    
  • 贡献者:Codex

    如果给定的自定义文章类型本质上是分层的,则可以使用wp_list_pages()列出该自定义文章类型的成员。在本例中,列出了自定义文章类型 Portfolio:

    $args = array(
    	'post_type' => 'portfolio',
    	'title_li'  => __( 'Portfolio', 'textdomain' )
    );
    wp_list_pages( $args ); 
    
  • 贡献者:PHPanos

    我没有看到任何地方可以传递sort_order参数。因此,我认为最好将其包含在args列表中,使其更加明显。

    这段代码按post_date对页面进行排序,并按降序对页面进行排序,以便首先获得最新的页面。

    wp_list_pages(array('sort_column' => 'post_date', 'sort_order' => 'desc'));
  • 贡献者:Codex

    列出子页面,即使在子页面上

    以上示例仅显示父页面中的子页面,而不是实际位于子页面上的子页面。当在父页面或其中一个子页面上时,此代码将显示子页面,并且仅显示子页面。

    如果将此代码放在边栏中的小工具块之后,则该代码将不起作用。

    <?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; ?>
    
  • 贡献者:Codex

    页面项目的标记和样式
    默认情况下,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>
    
  • 贡献者:Codex

    从列表中排除页面
    使用exclude参数从要由wp_list_pages生成的列表中隐藏某些页面。

    <ul>
    	<?php wp_list_pages( 'exclude=17,38' ); ?>
    </ul>
    
  • 贡献者:Codex

    仅列出此父级的所有顶级页面和子页面

    以下列出了所有顶级页面和

    如果在顶级页面上–仅此页面的子页面
    如果在子页面上–其同级页面,但不包括其他顶级页面的子页面

    $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>
    
  • 贡献者:Codex

    按页面顺序列出页面
    下面的例子是按照 "页面→编辑" 面板中各页的排序设置所定义的顺序列出各页。

    <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>
    
  • 贡献者:Codex

    此示例显示按(创建)日期排序的页面,并显示每个页面列表项旁边的日期。

    <ul>
    	<?php wp_list_pages( 'sort_column=post_date&show_date=created' ); ?>
    </ul>
    
  • 贡献者:Codex

    在列表中包含页面
    要仅包括列表中的某些页面,例如ID号为35、7、26和13的页面,请使用include参数。

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

    列出整个子页面

    这是如何获得整个子页面列表

    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; ?>
    
  • 贡献者:Codex

    列出父页面和所有子页面

    由于无法告诉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 );
    }
    ?>
    
  • 贡献者:Codex

    列出当前页面及其祖先和子页面

    本例将列出当前页面、当前页面的祖先和当前页面的子项,因为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; ?>
    
  • 贡献者:Codex

    列出最顶端的祖先及其直系子代

    此方法将显示当前页面的最顶层祖先以及最顶层祖先的直接子级。这可用于清洁次级导航。

    首先,创建以下函数(最好在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.