描述
将分类以列表的形式显示为链接。点击分类的链接,就可以访问该分类下的所有文章的存档页面。
注意: wp_list_categories() 和 list_cats() 以及 wp_list_cats() 的使用类似,但是后面 2 个已经弃用。
如果你希望不格式化输出分类,请使用 get_categories()
用法
<?php <a href="https://www.wpdaxue.com/tag/wp_list_categories" title="查看与【wp_list_categories】相关的文章" target="_blank" rel="noopener">wp_list_categories</a>( $args ); ?> |
默认用法
<?php $args = array( 'show_option_all' => '', 'orderby' => 'name', 'order' => 'ASC', 'style' => 'list', 'show_count' => 0, 'hide_empty' => 1, 'use_desc_for_title' => 1, 'child_of' => 0, 'feed' => '', 'feed_type' => '', 'feed_image' => '', 'exclude' => '', 'exclude_tree' => '', 'include' => '', 'hierarchical' => 1, 'title_li' => __( 'Categories' ), 'show_option_none' => __('No categories'), '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或文章数量等为排列依据。有效值:
- 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.
来源:
https://www.wpdaxue.com/wp_list_categories.html