WordPress函數(shù)：wp_list_categories（分類列表）

描述

將分類以列表的形式顯示為鏈接。點擊分類的鏈接，就可以訪問該分類下的所有文章的存檔頁面。

注意： wp_list_categories() 和 list_cats() 以及 wp_list_cats() 的使用類似，但是后面 2 個已經(jīng)棄用。

如果你希望不格式化輸出分類，請使用 get_categories()

用法

<?php wp_list_categories( $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
); ?>

默認用法輸出的效果：

• 無連接的分類
• 根據(jù)分類名稱對分類列表進行升序排列
• 以無序列表的樣式顯示
• 不顯示文章數(shù)量
• 只顯示有文章的分類
• 設(shè)置標題屬性到分類描述
• 子分類無限制
• 不顯示Feed和Feed圖像
• 不排除任何分類，并包括所有分類
• 為當前的分類添加CSS類’current-cat’
• 以分層縮進的方式顯示分類列表
• 在列表的頂部顯示“分類（Categories）”作為標題
• 沒有SQL限制（’number’ => 0 is not shown above）
• 顯示（輸出）分類
• 不限制顯示的深度
• 所有分類
• 使用一個新的Walker_Category 類對象 walker 來顯示列表

參數(shù)

show_option_all 

（字符串）非空值會導(dǎo)致如果樣式設(shè)置為列表顯示所有類別的鏈接。默認值是不顯示鏈接到所有分類。

orderby 

（字符串）以分類名稱、分類ID或文章數(shù)量等為排列依據(jù)。有效值：

• ID
• name – 默認
• slug
• count
• term_group

order 

（字符串）分類的排序順序（升序或降序）。缺省為升序。有效值：

• ASC – 升序（默認）
• DESC – 降序

style

（字符串）分類列表顯示的樣式。將分類列表的方式顯示（使用<br >標簽分隔列表項）。默認設(shè)置為列表（無序列表）。有效值：

• list – 默認
• none

show_count 

（布爾）顯示文章數(shù)量。默認情況下不顯示文章數(shù)量。有效值：

• 1 (True)
• 0 (False) – 默認

hide_empty

（布爾）隱藏沒有文章的分類。  默認情況下隱藏沒有文章的分類。有效值：

• 1 (True) – 默認
• 0 (False)

use_desc_for_title 

（布爾）是否將分類描述作為分類鏈接中的 title 屬性，默認為 true。有效值：

• 1 (True) – 默認
• 0 (False)

child_of 

（整數(shù)）只顯示此參數(shù)確定的分類的子分類。此參數(shù)沒有默認值。

feed 

（字符串）顯示每個分類的 RSS-2 Feed鏈接到設(shè)置的feed文字。默認不顯示feed文字和鏈接。

feed_type 

（字符串）

feed_image 

（字符串）設(shè)置一個圖片到分類的 RSS-2 Feed鏈接。這個參數(shù)會覆蓋上面的 feed 參數(shù)。此參數(shù)沒有默認值。

exclude 

（字符串）排除一個或多個分類。使用逗號分隔每個分類的ID。參數(shù) include 必須為空。

exclude_tree 

（字符串）排除分類樹。使用逗號分隔每個分類的ID。參數(shù) include 必須為空。如果 hierarchical 參數(shù) 為 true ，請使用 exclude 參數(shù)替代 exclude_tree 。

include 

（字符串）只顯示特定的分類，使用逗號分隔每個分類的ID。

hierarchical

（布爾）以層級來顯示分類的子分類。默認為 true（在分類的下面顯示它們的子分類）。有效值：

• 1 (True) – 默認
• 0 (False)

title_li 

（字符串）設(shè)置列表的標題。默認為“Categories”。如果存在這個參數(shù)，但是值為空，將無法顯示列表。

number

（整數(shù)）設(shè)置顯示的分類數(shù)量。定義SQL的限制值。默認為不限制。

echo

（布爾） 顯示結(jié)果或保存在一個變量里。默認為 True 。有效值：

• 1 (True) – 默認
• 0 (False)

depth 

（整數(shù)）顯示分類的深度（即顯示多少層的子分類）。默認值為 0（顯示所有分類和子分類）。有效值：

• 0 – 所有分類和子分類（默認）
• -1 – 所有類別顯示在平面（不縮進）的形式（覆蓋hierarchical）。
• 1 – 只顯示頂級分類
• n – 根據(jù)n的具體數(shù)字來顯示對應(yīng)等級的分類。

current_category 

（整數(shù)）后跟分類ID號，對此ID分類加入名為current-cat的CSS控制，用戶自定義current-cat樣式后，可用于突出顯示。

pad_counts

（布爾）計算包括子分類的鏈接或文章數(shù)。如果 show_counts 和 hierarchical 為  true ，這個參數(shù)就自動設(shè)置為  true 。有效值：

• 1 (true)
• 0 (false) – 默認

taxonomy 

（字符串）要返回的分類法。該參數(shù)是在 3.0 中添加的。有效值：

• category – 默認
• taxonomy – 或任何其他已注冊的分類法

walker 

（對象）生成列表 Walker 類。有效值：

object – an instance of a class that extends either Walker_Category or Walker 【不是很理解這個參數(shù)的作用，如果有朋友清楚，煩請告知，謝謝】

例子

包含或排除分類

按字母順序排序分類，只包括類別ID為 16，3，9和5 的分類，你可以使用下面的代碼：

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

根據(jù)名稱排列，顯示文章數(shù)，并且排除ID為 10 的分類：

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

顯示或隱藏列表的標題

title_li 參數(shù)可以設(shè)置或隱藏 wp_list_categories 函數(shù)生成的列表 的標題。默認標題為“分類（Categories）” 。如果設(shè)置為空值，就不會顯示標題。排除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 的分類的子分類，根據(jù)ID排序，顯示文章數(shù)，并且將分類描述作為連接的 title屬性。注意：如果父分類沒有文章，將不顯示父分類。

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

移除分類計數(shù)的括號

當 show_count=1 ，每個分類的后面都將顯示文章數(shù)，同時使用括號包含。如果你要移除括號，可以使用下面的代碼

<?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 連接

根據(jù)分類名稱進行排序，顯示文章數(shù)量，并且顯示每個分類的 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 參數(shù)到  wp_list_categories() 。讓你可以通過 taxonomy 參數(shù)來設(shè)置要顯示的是哪種分類法下的分類項目。比如要顯示分類法為 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>

顯示文章對應(yīng)的分類

根據(jù)父-子關(guān)系來排序文章的分類。類似于 get_the_category_list() 函數(shù)（根據(jù)名稱排序分類）。下面的例子必須使用在循環(huán)中：

<?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"。

你可以通過設(shè)置 title_li 為空值來隱藏標題。你可以自定義包裝 有序列表或無序列表。如果你不需要以列表輸出分類，可以將 style 參數(shù)設(shè)置為 none。

你可以根據(jù)下面的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 { ... }

函數(shù)歷史

開始于 2.1 版本

2.3.0 : 添加 echo 參數(shù)

2.5.0 : 添加 depth 參數(shù)

2.6.0 : 添加 current_category 參數(shù)

2.7.1 : 添加 exclude_tree 參數(shù)

2.9.0 : 添加 pad_counts 參數(shù)

3.0.0 : 添加 taxonomy 參數(shù)

3.4.0 : 移除 show_last_update 參數(shù)

源文件

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