wp_list_categories函数
- 发表于
- WordPress
wp_list_categories 是 WordPress 中列出分类目录的一个函数。WordPress中的文章被存放在不同的分类目录下，在 CMS 中，分类目录通常被称之为“栏目”。如果用户要修改或制作一个 WordPress模板，wp_list_categories 是注定要被用到的一个函数。
普通用法
|
1 2 3 4 5 6 7 8 |
<?PHP //用法1 wp_list_categories(); //用法2 $CategoriesInfo = array(); wp_list_categories($CategoriesInfo); ?> |
参数说明：
一、和分类目录数量有关的参数
和分类目录数量有关的参数有三个，分别是 exclude、include、number。
exclude：
按照分类目录的 ID 排除分类目录。参数为1个或者多个数字，显示出来的分类目录中，如果某个或者某几个分类目录的 ID和参数中指定的数字相等，则这些分类目录不会被显示出来。
用法
|
1 2 3 4 5 6 7 8 9 10 11 |
<?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的分类目录被显示出来。
用法
|
1 2 3 4 5 6 7 8 9 10 11 |
<?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 设置的值为准。
用法：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<?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’升序。
用法
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<?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 链接设置一个图标。为字符串，一般情况下是一个图片文件的相对或绝对地址。默认不显示。
用法
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<?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，则没有任何样式，分类列表之间以“
”分割。
用法
|
1 2 3 4 5 6 7 |
<?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。
用法
|
1 2 3 4 5 6 7 8 9 10 |
<?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优先 |
用法
|
1 2 3 4 5 6 7 8 |
<?PHP //不同级别的分类目录出现在互相嵌套的ul和li中 wp_list_categories('hierarchical=1'); //不同级别的分类目录出现在同一级别的ul和li中 $CategoriesInfo = array( 'hierarchical' => 0 ); wp_list_categories($CategoriesInfo); ?> |
show_count
是否显示出来分类目录中所包含的文章数量，参数为1或者0，默认为0，不显示文章数量，如果设置为1，则显示出来文章数量。
用法
|
1 2 3 4 5 6 7 |
<?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不起作用。
|
1 2 3 4 5 6 7 8 |
<?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时，则只显示这个分类下的子分类。
用法
|
1 2 3 4 5 6 7 8 |
<?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函数的结果会产生一个变量，显示这个变量的时候才显示出来分类目录。
用法
|
1 2 3 4 5 6 7 8 9 10 11 |
<?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的时候，显示没有文章的分类目录。
|
1 2 3 4 5 6 7 |
<?PHP //显示所有分类目录链接(不管这些分类目录是否包含文章) wp_list_categories('hide_empty=0'); //只显示包含有文章的分类目录链接 wp_list_categories('hide_empty=1'); ?> |
use_desc_for_title
分类目录的描述信息，是否加入到分类目录链接的 title标签中。可以设置为1或者0，1为默认值，加入title标签，内容为分类目录的描述信息，0为不加入。
|
1 2 3 4 5 6 7 |
<?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。官方文档的示例中写的是：
|
1 |
'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，不过这两个我都没有试出来效果。有知道的朋友可以给我留 言，谢谢。
