明泉 » wp_list_categories http://liumingquan.net 开尽春花芳草涧 遍通秋水月明泉 Fri, 16 Jul 2010 05:37:44 +0000 http://wordpress.org/?v=2.9.2 en hourly 1 wp_list_categories http://liumingquan.net/html/2010_02/wp_list_categories.html http://liumingquan.net/html/2010_02/wp_list_categories.html#comments Mon, 08 Feb 2010 06:29:30 +0000 admin http://liumingquan.net/html/2010_02/wp_list_categories.html wp_list_categories 是 WordPress 中列出分类目录的一个函数。WordPress 中的文章被存放在不同的分类目录下，在 CMS 中，分类目录通常被称之为“栏目”。如果用户要修改或制作一个 WordPress 模板，wp_list_categories 是注定要被用到的一个函数。

普通用法

<?PHP
	//用法1
	wp_list_categories();
 
	//用法2
	$CategoriesInfo = array();
	wp_list_categories($CategoriesInfo);
?>

参数说明：

一、和分类目录数量有关的参数
和分类目录数量有关的参数有三个，分别是 exclude、include、number。

exclude：
按照分类目录的 ID 排除分类目录。参数为1个或者多个数字，显示出来的分类目录中，如果某个或者某几个分类目录的 ID 和参数中指定的数字相等，则这些分类目录不会被显示出来。

用法

<?PHP
	//不显示Id为1的目录
	wp_list_categories('exclude=1');
 
	//不显示Id为3、4、5的分类目录
	wp_list_categories('exclude=3,4,5');
 
	//不显示Id为3、4、6的分类目录
	$CategoriesInfo = array('exclude' => '3,4,6');
	wp_list_categories($CategoriesInfo);
?>

include：
设置 include 为分类目录的 ID，则只显示经 include 指定的分类目录(不包括这个 ID 所指分类目录的下级目录)。include 的优先级大于 exclude，当参数设置为include=1&exclude=1的时候(看起来这种设置很无厘头)，则 ID 为1的分类目录被显示出来。

用法

<?PHP
	//只显示id为1的分类目录
	wp_list_categories('include=1');
 
	//只显示id为2,3的分类目录
	wp_list_categories('include=2,3');
 
	//只显示Id为3、4、6的分类目录
	$CategoriesInfo	= array('include' => '3,4,6');
	wp_list_categories($CategoriesInfo);
?>

number
所显示的分类目录的数量。为数字。默认没有限制。number 的优先级大于 include，当 include 中设置的应显示出来的分类目录的数量大于 number 中设置的值时，以 number 设置的值为准。

用法：

<?PHP
	//只显示出来3个分类目录
	wp_list_categories('number=3');
 
	//只显示出来id为1、2、3的分类目录
	//(尽管include希望显示出来7个分类目录，但number的优先级大于include)
	wp_list_categories('include=1,2,3,4,5,6,7&number=3');
 
	//只显示出来id为1、2、3、4的分类目录
	//(尽管include希望显示出来7个分类目录，但number的优先级大于include)
	$CategoriesInfo = array( 'include' => '1,2,3,4,5,6,7',
				 'number' =>  '4');
	wp_list_categories($CategoriesInfo);
?>

二、和分类目录排序有关的参数
和分类目录排序有关的参数有两个，orderby 和 order

orderby：
所列出来的分类目录排序的依据。参数可以是‘ID’、‘name’或‘count’，分别是按照分类目录的 ID、名称和文章数量来排序。其默认值是‘ID’。

order：
所列出来分类目录排序的方式，升序还是降序，参数可以是‘ASC’或‘DESC’，默认值是‘ASC’升序。

用法

<?PHP
	//按照ID的降序排列
	wp_list_categories('orderby=ID&order=DESC');
 
	//按照ID的升序排列
	wp_list_categories('orderby=ID&order=ASC');
 
	//按照分类目录名称的升序排列
	wp_list_categories('orderby=name&order=ASC');
 
	//按照文章数量的降序排列
	$CategoriesInfo = array( 'orderby' => 'count',
				 'order' =>  'DESC');
	wp_list_categories($CategoriesInfo);
?>

三、和 feed 有关的参数
和 feed 有关的参数有两个， feed 和 feed_image

feed：
是否显示分类目录的 rss 链接。为字符串，feed所指定的字符串为链接的文字，默认不显示。

feed_image：
为 rss 链接设置一个图标。为字符串，一般情况下是一个图片文件的相对或绝对地址。默认不显示。

用法

<?PHP
	//显示 rss 链接
	wp_list_categories('feed=RSS');
 
	//显示 rss 链接，并有小图标显示
	wp_list_categories('feed=RSS&feed_image=/wp-content/themes/default/images/rss.jpg');
 
	//显示 rss 链接，并有小图标显示
	$CategoriesInfo = array	( 'feed' => 'RSS',
				  'feed_image' => '/wp-content/themes/default/images/rss.jpg');
	wp_list_categories($CategoriesInfo);
?>

四、和显示样式（方式）有关的参数

style：
分类目录是以列表的方式显示出来，还是以没有任何样式的方式显示出来。参数为list或者none，默认是list，是以ui、li列表方式显示出来，如果设置为none，则没有任何样式，分类列表之间以“
”分割。

用法

<?PHP
	//以列表的方式显示
	wp_list_categories('style=list');
 
	//以“<br />”分割
	wp_list_categories('style=none');
?>

depth：
参数为数字，可以是1、2、3、…n，或者是0和-1，默认值为0。当depth为正整数的时候，可以控制显示几层分类，例如depth为1，则只显示一层分类，如depth为2，则显示一层分类及这层分类之下的子分类。如果设置depth为-1时，不同级别的分类目录是在一个ul之中的同级别的li，当depth为0时，不同级别的分类是嵌套在不同ul之间的li。

用法

<?PHP
	//不同级别的分类目录在同一个ul之中同一级别的li之中显示
	wp_list_categories('depth=-1');
 
	//不同级别的分类目录在不同的ul之中同一级别的li之中显示
	wp_list_categories('depth=0');
 
	//显示两个级别的分类目录
	wp_list_categories('depth=2');
?>

hierarchical：
数字，1或者0，默认为1，为1的时候，不同级别的分类目录现在在互相嵌套的ul和li中，为0的时候，不同级别的分类目录显示在同一级别的ul和li中。hierarchical和depth有点相似，两者一起使用并且矛盾的话，分类目录总是显示在同级的ul之下。

depth 0 -1 NULL NULL 0 -1 0 -1
hierarchical NULL NULL 0 1 1 0 0 1
  嵌套ul 同级ul 同级ul 嵌套ul 嵌套ul 同级ul 同级ul 同级ul
              hierarchical优先 depth优先

用法

<?PHP
	//不同级别的分类目录出现在互相嵌套的ul和li中
	wp_list_categories('hierarchical=1');
 
	//不同级别的分类目录出现在同一级别的ul和li中
	$CategoriesInfo = array( 'hierarchical' => 0 );
	wp_list_categories($CategoriesInfo);
?>

show_count
是否显示出来分类目录中所包含的文章数量，参数为1或者0，默认为0，不显示文章数量，如果设置为1，则显示出来文章数量。

用法

<?PHP
	//显示出来文章数量
	wp_list_categories('show_count=1');
 
	//不显示出来文章数量
	wp_list_categories('show_count=0');
?>

show_option_all：
在wp_list_categories中使用show_option_all参数的话，在所有分类目录之前，将产生一个到博客首页的链接，链接的文字就是show_option_all所指定的值。
//用法
wp_list_categories('show_option_all=首页');
?>

五、和标题有关的参数

title_li
在分类目录之前显示标题。默认值为po文件中Categories所对应的译文，官方中文版po文件中Categories的译文是“分类目录”，也可以设置为其他的值。当style设置为none的时候，title_li不起作用。

<?PHP
	//显示“栏目”
	wp_list_categories('title_li=栏目');
 
	//显示po文件中Categories所对应的译文
	$CategoriesInfo = array( 'title_li'=> __('Categories'));
	wp_list_categories($CategoriesInfo);
?>

六、其他参数

child_of：
参数为数字，功能为显示指定父分类 ID 下的子分类，无默认值。假设某个分类的id为6，将child_of设置为6时，则只显示这个分类下的子分类。

用法

<?PHP
	//显示ID为6的分类目录的下一级分类目录
	wp_list_categories(child_of=6);
 
	//显示ID为1的分类目录的下一级分类目录
	$CategoriesInfo = array('child_of' => 1);
	wp_list_categories($CategoriesInfo);
?>

echo：
参数为数字，1或者0，默认是1。如果是1的话，wp_list_categories函数将分类目录正常显示出来。如果是0的话，使用wp_list_categories函数的结果会产生一个变量，显示这个变量的时候才显示出来分类目录。

用法

<?PHP
	//如果将echo设置为0，需要增加echo以便显示出来分类目录
	$temp = wp_list_categories('echo=0');
	echo $temp;
 
	//如果将echo设置为1，则直接可以显示出来分类目录
	wp_list_categories('echo=1');
 
	//其实echo的默认值就是1，所以可以直接用如下的写法
	wp_list_categories();
?>

hide_empty：
数字，1或者0，默认为1。控制是否显示还没有文章的分类目录。默认为1，不显示没有文章的分类目录，当设置为0的时候，显示没有文章的分类目录。

<?PHP
	//显示所有分类目录链接(不管这些分类目录是否包含文章)
	wp_list_categories('hide_empty=0');
 
	//只显示包含有文章的分类目录链接
	wp_list_categories('hide_empty=1');
?>

use_desc_for_title
分类目录的描述信息，是否加入到分类目录链接的 title 标签中。可以设置为1或者0，1为默认值，加入title标签，内容为分类目录的描述信息，0为不加入。

<?PHP
	//加入title标签
	wp_list_categories('use_desc_for_title=1');
 
	//不加入title信息
	wp_list_categories('use_desc_for_title=0');
?>

七、有疑问的参数

show_last_update
官方的文档中说这个参数是显示分类中日志的最新时间戳，可以是1或者0。但是我没有试验出来这个参数的效果。并且发现官方文档中也有一些BUG。官方文档的示例中写的是：

    'show_last_update'   => 0,

但同一页面的下边解释这个参数的时候，却是：
show_last_updated
(boolean) Should the last updated timestamp for posts be displayed (TRUE) or not (FALSE). Defaults to FALSE.

* 1 (True)
* 0 (False) – Default

能够看到，show_last_update变成了show_last_updated，不过这两个我都没有试出来效果。有知道的朋友可以给我留言，谢谢。

]]> http://liumingquan.net/html/2010_02/wp_list_categories.html/feed 6