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

相关函数:

阿里云