wp_list_categories

描述

将分类以列表的形式显示为链接。点击分类的链接，就可以访问该分类下的所有文章的存档页面。

注意： wp_list_categories() 和 list_cats() 以及 wp_list_cats() 的使用类似，但是后面 2 个已经弃用。

如果你希望不格式化输出分类，请使用 get_categories()

用法

<?PHP wp_list_categories( $args ); ?>

默认用法

wp_list_categories ( $args );
$args = array (
'show_option_all' => '', // 是否列出分类链接
'orderby' => 'name', // 按名称排列
'order' => 'ASC', // 升、降序
'style' => 'list', // 是否用列表（ul>li）
'show_count' => 0, // 是否显示文章数量
'hide_empty' => 1, // 是否显示无日志分类
'use_desc_for_title' => 1, // 是否显示分类描述
'child_of' => 0, // 是否限制子分类
'feed' => '', // 是否显示rss
'feed_type' => '', // rss类型
'feed_image' => '', // 是否显示rss图片
'exclude' => '', // 排除分类的ID，多个用',（英文逗号）'分隔
'exclude_tree' => '', // 排除分类树，即父分类及其下的子分类
'include' => '', // 包括的分类
'hierarchical' => true, // 是否将子、父分类分级
'title_li' => __ ( 'Categories' ), // 列表标题的名称
'show_option_none' => __ ( 'Nocategories' ), // 无分类时显示的标题
'number' => null, // 显示分类的数量
'echo' => 1, // 是否显示，显示或者返回字符串
'depth' => 0, // 层级限制
'current_category' => 0, // 添加一个没有的分类
'pad_counts' => 0, // 这个我也不明白
'taxonomy' => 'category', // 使用的分类法
'walker' => null  // 用于显示的类（很复杂的概念）
);

默认用法输出的效果：

无连接的分类

根据分类名称对分类列表进行升序排列

以无序列表的样式显示

不显示文章数量

只显示有文章的分类

设置标题属性到分类描述

子分类无限制

不显示Feed和Feed图像

不排除任何分类，并包括所有分类

为当前的分类添加CSS类'current-cat'

以分层缩进的方式显示分类列表

在列表的顶部显示“分类（Categories）”作为标题

没有SQL限制（'number' => 0 is not shown above）

显示（输出）分类

不限制显示的深度

所有分类

使用一个新的Walker_Category 类对象 walker 来显示列表

参数

show_option_all

（字符串）非空值会导致如果样式设置为列表显示所有类别的链接。默认值是不显示链接到所有分类。

orderby

（字符串）以分类名称、分类ID或文章数量等为排列依据。有效值：

name - 默认

slug

count

term_group

order

（字符串）分类的排序顺序（升序或降序）。缺省为升序。有效值：

ASC – 升序（默认）

DESC - 降序

style

（字符串）分类列表显示的样式。将分类列表的方式显示（使用<br >标签分隔列表项）。默认设置为列表（无序列表）。有效值：

list – 默认

none

show_count

（布尔）显示文章数量。默认情况下不显示文章数量。有效值：

1 (True)

0 (False) - 默认

hide_empty

（布尔）隐藏没有文章的分类。默认情况下隐藏没有文章的分类。有效值：

1 (True) – 默认

0 (False)

use_desc_for_title

（布尔）是否将分类描述作为分类链接中的 title 属性，默认为 true。有效值：

1 (True) – 默认

0 (False)

child_of

（整数）只显示此参数确定的分类的子分类。此参数没有默认值。

feed

（字符串）显示每个分类的 RSS-2 Feed链接到设置的feed文字。默认不显示feed文字和链接。

feed_type

（字符串）

feed_image

（字符串）设置一个图片到分类的 RSS-2 Feed链接。这个参数会覆盖上面的 feed 参数。此参数没有默认值。

exclude

（字符串）排除一个或多个分类。使用逗号分隔每个分类的ID。参数 include 必须为空。

exclude_tree

（字符串）排除分类树。使用逗号分隔每个分类的ID。参数 include 必须为空。如果 hierarchical 参数为 true ，请使用 exclude 参数替代 exclude_tree 。

include

（字符串）只显示特定的分类，使用逗号分隔每个分类的ID。

hierarchical

（布尔）以层级来显示分类的子分类。默认为 true（在分类的下面显示它们的子分类）。有效值：

1 (True) – 默认

0 (False)

title_li

（字符串）设置列表的标题。默认为“Categories”。如果存在这个参数，但是值为空，将无法显示列表。

number

（整数）设置显示的分类数量。定义SQL的限制值。默认为不限制。

echo

（布尔）显示结果或保存在一个变量里。默认为 True 。有效值：

1 (True) – 默认

0 (False)

depth

（整数）显示分类的深度（即显示多少层的子分类）。默认值为 0（显示所有分类和子分类）。有效值：

0 - 所有分类和子分类（默认）

-1 - 所有类别显示在平面（不缩进）的形式（覆盖hierarchical）。

1 - 只显示顶级分类

n - 根据n的具体数字来显示对应等级的分类。

current_category

（整数）后跟分类ID号，对此ID分类加入名为current-cat的CSS控制，用户自定义current-cat样式后，可用于突出显示。

pad_counts

（布尔）计算包括子分类的链接或文章数。如果 show_counts 和 hierarchical 为 true ，这个参数就自动设置为 true 。有效值：

1 (true)

0 (false) - 默认

taxonomy

（字符串）要返回的分类法。该参数是在 3.0 中添加的。有效值：

category - 默认

taxonomy - 或任何其他已注册的分类法

walker

（对象）生成列表 Walker 类。有效值：

object - an instance of a class that extends either Walker_Category or Walker 【不是很理解这个参数的作用，如果有朋友清楚，烦请告知，谢谢】

例子

包含或排除分类

按字母顺序排序分类，只包括类别ID为 16，3，9和5 的分类，你可以使用下面的代码：

<ul>
    <?php wp_list_categories('orderby=name&include=3,5,9,16'); ?> 
    </ul>

根据名称排列，显示文章数，并且排除ID为 10 的分类：

  <ul>
    <?php wp_list_categories('orderby=name&show_count=1&exclude=10'); ?> 
    </ul>

显示或隐藏列表的标题

title_li 参数可以设置或隐藏 wp_list_categories 函数生成的列表的标题。默认标题为“分类（Categories）” 。如果设置为空值，就不会显示标题。排除ID为 4 和 7 的分类，同时隐藏标题：

<ul>
    <?php wp_list_categories('exclude=4,7&title_li='); ?>
    </ul>

只显示ID为 5、9 和23 的分类，并且列表的标题改为 Poetry ，而且使用 <h2> 标签包含：

<ul>
    <?php wp_list_categories('include=5,9,23&title_li=<h2>' . __('Poetry') . '</h2>' ); ?> 
    </ul>

只显示指定分类的子分类

显示ID为 8 的分类的子分类，根据ID排序，显示文章数，并且将分类描述作为连接的 title属性。注意：如果父分类没有文章，将不显示父分类。

<ul> 
    <?php wp_list_categories('orderby=id&show_count=1&use_desc_for_title=0&child_of=8'); ?>
    </ul>

移除分类计数的括号

当 show_count=1 ，每个分类的后面都将显示文章数，同时使用括号包含。如果你要移除括号，可以使用下面的代码

<?php
    $variable = wp_list_categories('echo=0&show_count=1&title_li=<h2>Categories</h2>');
    $variable = preg_replace('~\((\d+)\)(?=\s*+<)~', '$1', $variable);
    echo $variable;
    ?>

显示分类和 RSS Feed 连接

根据分类名称进行排序，显示文章数量，并且显示每个分类的 RSS 订阅链接：

  <ul>
    <?php wp_list_categories('orderby=name&show_count=1&feed=RSS'); ?>
    </ul>

使用Feed 图标替换文本，可以使用下面的代码：

<ul>
    <?php wp_list_categories('orderby=name&show_count=1&feed_image=/images/rss.gif'); ?>
    </ul>

显示自定义分类法的项目

在3.0版本添加了taxonomy 参数到 wp_list_categories() 。让你可以通过 taxonomy 参数来设置要显示的是哪种分类法下的分类项目。比如要显示分类法为 genre 的分类列表：

  <?php 
    //list terms in a given taxonomy using wp_list_categories (also useful as a widget if using a PHP Code plugin)
     
    $taxonomy     = 'genre';
    $orderby      = 'name'; 
    $show_count   = 0;      // 1 for yes, 0 for no
    $pad_counts   = 0;      // 1 for yes, 0 for no
    $hierarchical = 1;      // 1 for yes, 0 for no
    $title        = '';
     
    $args = array(
      'taxonomy'     => $taxonomy,
      'orderby'      => $orderby,
      'show_count'   => $show_count,
      'pad_counts'   => $pad_counts,
      'hierarchical' => $hierarchical,
      'title_li'     => $title
    );
    ?>
     
    <ul>
    <?php wp_list_categories( $args ); ?>
    </ul>

显示文章对应的分类

根据父-子关系来排序文章的分类。类似于 get_the_category_list() 函数（根据名称排序分类）。下面的例子必须使用在循环中：

<?php
    // get the category IDs assigned to post
    $categories = wp_get_post_categories( $post->ID, array( 'fields' => 'ids' ) );
    // separator between links
    $separator = ', ';
     
    if ( $categories ) {
     
    $cat_ids = implode( ',' , $categories );
    $cats = wp_list_categories( 'title_li=&style=none&echo=0&include=' . $cat_ids );
    $cats = rtrim( trim( str_replace( '<br />',  $separator, $cats ) ), $separator );
     
    // display post categories
    echo  $cats;
    }
    ?>

标记和样式化分类列表

默认情况下， wp_list_categories() 生成的是无序列表（ul），使用 <li> 标签来包含每个分类，而且列表的标题为"Categories"。

你可以通过设置 title_li 为空值来隐藏标题。你可以自定义包装有序列表或无序列表。如果你不需要以列表输出分类，可以将 style 参数设置为 none。

你可以根据下面的CSS选择器来样式化输出：

 li.categories { ... }  /* outermost list item */
     li.cat-item { ... }
     li.cat-item-7 { ... }  /* category ID #7, etc */
     li.current-cat { ... }
     li.current-cat-parent { ... }
     ul.children { ... }

函数历史

开始于 2.1 版本

2.3.0 : 添加 echo 参数

2.5.0 : 添加 depth 参数

2.6.0 : 添加 current_category 参数

2.7.1 : 添加 exclude_tree 参数

2.9.0 : 添加 pad_counts 参数

3.0.0 : 添加 taxonomy 参数

3.4.0 : 移除 show_last_update 参数

源文件

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

WordPress开发手册

wp_list_categories

描述

用法

默认用法

参数

例子

函数历史

源文件