WordPress分类列表标签：wp_list_categories

WordPress模板标签wp_list_categories用于输出分类列表，通常在导航栏需要用到

wp_list_categories( string|array $args = '' )

函数参数

$args

数组或字符串值

wp_list_categories()函数$args参数默认的值如下：

$args = array(
	'child_of'            => 0,
	'current_category'    => 0,
	'depth'               => 0,
	'echo'                => 1,
	'exclude'             => '',
	'exclude_tree'        => '',
	'feed'                => '',
	'feed_image'          => '',
	'feed_type'           => '',
	'hide_empty'          => 1,
	'hide_title_if_empty' => false,
	'hierarchical'        => true,
	'order'               => 'ASC',
	'orderby'             => 'name',
	'separator'           => '<br />',
	'show_count'          => 0,
	'show_option_all'     => '',
	'show_option_none'    => __( 'No categories' ),
	'style'               => 'list',
	'taxonomy'            => 'category',
	'title_li'            => __( 'Categories' ),
	'use_desc_for_title'  => 1,
);

wp_list_categories()函数$args参数可用的值如下：

child_of

整数型，默认值：0

指定一个分类ID，将输出该分类下的子分类，但不包括该分类。

current_category

整数型或数组，默认值：0

默认情况下，当前分类会有一个名为current-cat的class，以本站为例，当点击“开发”这个分类转到“开发”分类页面，那么“开发”这个li元素就有一个名为current-cat的class，便于我们设置CSS样式。

如果这个参数指定了一个或多个分类ID，那么始终为指定的这些分类li元素添加一个名为current-cat的class，而当前分类不会再有current-cat这个class

depth

整数型，默认值：0

• 0：输出所有的分类和子分类；
• 1：只输出顶级分类，不包含任何子分类；
• n：根据n的具体数字来显示相应等级的分类；
• -1：输出所有的分类和子分类，不论hierarchical的值是多少，都不以层级的方式输出；

echo

布尔值，默认值：1

默认直接输出分类列表，如果为0则只返回结果而不输出。

exclude

数组或字符串，默认为空

要排除的分类ID，如果为字符串值时，多个分类ID用逗号分隔。如果hierarchical为true，则相应的子分类也会被排除。

exclude_tree

数组或字符串，默认为空

要排除的分类ID，不管hierarchical为何值，相应的子分类都会被排除。

feed

字符串值，默认为空

分类feed链接的锚文本，默认不显示feed链接。

feed_image

字符串值，默认为空

提供一个图片的URL，将用这个图片作为feed的链接

feed_type

字符串值，默认为空

指定feed的类型

hide_empty

布尔值，默认值：1

是否隐藏没有文章的分类，默认隐藏，为0则会显示没有文章的分类。如果分类是以层级的方式显示的，那么只要子分类下有文章，父分类都会显示。

hide_title_if_empty

布尔值，默认值：false

在没有分类目录时，是否隐藏标题“分类目录”，默认无论何时都显示标题“分类目录”

hierarchical

布尔值，默认值：true

默认情况下，以层级的方式输出所有父分类和子分类，也就是说子分类被嵌套在父分类的<li>里。

order

字符串值，默认值：ASC

分类的排序顺序

• ASC：升序排列；
• DESC：降序排列；

orderby

字符串值，默认值：name

以何种方式排序

• ID：分类的ID
• name：分类名称
• slug：分类别名
• count：文章数量
• term_group

separator

字符串值，默认值：<br />

当style的值为none时，以什么标记来分隔分类链接，默认<br />

show_count

布尔值，默认值：0

是否显示分类下的文章数量，默认不显示

show_option_all

字符串值，默认为空

提供一个文本作为“所有链接”的锚文本，也就是在链接列表的开始处添加一个“所有链接”的<li>项。

show_option_none

字符串值，默认值：No categories

当没有分类目录时要显示的文本

style

字符串值，默认值：list

分类列表以何种HTML标签输出

• list：以<li>列表输出
• none：仅输出链接，链接之间的标记由separator的值决定，默认为<br />

taxonomy

字符串值，默认值：category

要返回的分类法名称

title_li

字符串值，默认值：Categories

设置列表的标题，一般情况下我们在导航栏输出分类列表都不需要标题，因此可以传递一个空值。

use_desc_for_title

布尔值，默认值：1

是否将分类的描述作为a标签的title属性值，为了列表干净，可以传递一个空值

函数使用示例

以分类的文章总数降序排列，显示分类的文章数量，并排除ID为1的分类

<ul>
    <?php wp_list_categories( array(
        'orderby' => 'count',
		'order' => 'DESC',
        'show_count' => true,
        'exclude' => array( 1 )
    ) ); ?> 
</ul>

下面的代码输出同样的结果：

<ul>
    <?php wp_list_categories('orderby=count&order=DESC&show_count=1&exclude=1'); ?> 
</ul>

扩展阅读

wp_list_categories()函数位于：wp-includes/category-template.php