编辑“WordPress模板标签之wp list pages”

<span style="border:1px solid #000; text-align:center; float:right; padding:6px;"><strong>导航:</strong> [[WordPress开发文档|上一页]] | {{Template:WordPress导航}}</span>
<div style="clear:both;"></div>
==说明==
模板标签<STRONG>wp_list_pages( )</STRONG>将WordPress[http://www.wordpress.la/codex-%E9%A1%B5%E9%9D%A2%E7%9A%84%E5%88%9B%E5%BB%BA%E5%92%8C%E4%BD%BF%E7%94%A8.html 页面]作为链接显示出来。

该模板标签常用于自定义[http://www.wordpress.la/codex-%E8%87%AA%E5%AE%9A%E4%B9%89%E4%BE%A7%E8%BE%B9%E6%A0%8F.html 侧边栏]或[http://www.wordpress.la/codex-%E8%AE%BE%E8%AE%A1WordPress%E6%A0%87%E9%A2%98%E6%A0%8F.html 标题]，也常用于其他[http://www.wordpress.la/codex-WordPress%E6%A8%A1%E6%9D%BF%E6%96%87%E4%BB%B6.html 模板]中。

该模板标签在WordPress 1.5及更新版本中可用。

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

示例
默认用法
 $defaults = 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'  => '',      
    'exclude_tree'=> '' );
默认情况下，以上用法表明：
*显示所有页面和子页面（无深度限制） 
*不显示创建日期 
*不局限于child_of页面 
*不删除任何页面 
*页面列表的标题为“Pages（页面）” 
*回显（显示）结果 
*不局限于特定作者 
*先按页面顺序再按页面标题排序 
*按升序排列（不按上文中的默认状态显示） 
*以继承缩进格式显示页面（不按上文中的默认状态显示） 
*包含所有页面（不按上文中的默认状态显示） 
*不局限于特定元关键字/元值的页面（不按上文中的默认状态显示） 
*不删除父级/子级树 
 wp_list_pages();  

==隐藏或改变列表标题==
给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>

==将页面按页面顺序排列==
下面的例子将页面按管理栏中页面>编辑页面中 定义的页面顺序进行排列。
 < 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>  
==显示子页面==
2.0.1之前版本：

将以下代码存入[http://www.wordpress.la/theme.html WordPress主题]page.php模板中the_content( )之后的the_post版块中，或存入page.php模板的副本中，供含有子页面的页面使用：
 < ul>    
  <?php    
  global $id;    
  wp_list_pages("title_li=&child_of=$id&show_date=modified    
  &date_format=$date_format"); ?>  
 </ul>
由于未设置全局变量$id，本代码无法在WordPress2.0.1及之后版本的页面模板中运行。2.0.1及之后版本中可使用下面介绍的代码。

==WordPress 2.0.1及之后版本==

注意：即使没有子页面，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( )生成一个嵌套的、由管理栏页面>编辑页面生成的无序WordPress页面列表。将title_li参数设为任意空字符后可除去最外围选项（li.pagenav）和列表（ul）。


所有wp_list_pages( )生成的列表项（ li）都被标上page_item类。显示页面时将调用wp_list_pages( )，这时该页面的列表项被赋予附加类current_page_item。
 < li class="pagenav">  
 Pags [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为每篇文章或页面设定的独有的数字，而页面顺序则由用户在管理栏的页面>编辑页面中设置。 
*'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>，< 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或更新版本）

'''link_after（字符）'''

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

==相关条目==
*[[Drupal]] 
*[[OBLOG]] 
*[[X-Space]] 
*[[SaBlog-X]] 
*[[Bo-Blog]]

[[category:WordPress中文文档|M]]
[[category:WordPress网站开发|M]]
[[category:WordPress开发文档|M]]