wp_list_categories函数

wp_list_categories 是 WordPress 中列出分类目录的一个函数。WordPress 中的文章被存放在不同的分类目录下,在 CMS 中,分类目录通常被称之为“栏目”。如果用户要修改或制作一个 WordPress 模板,wp_list_categories 是注定要被用到的一个函数。

普通用法

参数说明:

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

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

用法

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

用法

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

用法:

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

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

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

用法

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

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

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

用法

四、和显示样式(方式)有关的参数

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

用法

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

用法

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优先

用法

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

用法

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不起作用。

六、其他参数

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

用法

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

用法

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

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

七、有疑问的参数

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

但同一页面的下边解释这个参数的时候,却是:
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,不过这两个我都没有试出来效果。有知道的朋友可以给我留 言,谢谢。