WordPress 分類列表函數 wp_list_categories 參數完整指南與實戰範例

wp_list_categories() 是 WordPress 核心函數，用於輸出或回傳分類連結列表。雖然內建小工具已涵蓋常見需求，但掌握此函數能實現更精細的客製化輸出，特別在主題開發與特殊版面需求時不可或缺。

函數簽名與完整參數表

wp_list_categories( $args );

$args 可為查詢字串或關聯陣列，完整參數如下：

關鍵參數深度解析

pad_counts：文章數遞迴累加

當 hierarchical=true 且 show_count=true 時，pad_counts=true 會將子分類的文章數累加到父分類計數中。預設為 false，父分類僅顯示直屬文章數。

taxonomy：支援自訂分類法

不限於預設「分類」，傳入自訂分類法 slug（如 'genre'、'product_cat'）即可輸出對應術語列表，極大擴展應用範圍。

walker：完全掌控輸出結構

繼承 Walker_Category 或 Walker 類別，覆寫 start_el()、end_el() 等方法，可產出任意 HTML 結構（如 Bootstrap 選單、JSON 格式等）。

實戰範例集

範例 1：指定分類、按名稱排序

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

範例 2：自訂標題、包含特定分類

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

範例 3：陣列式參數、自訂分類法

<?php
$args = array(
    'taxonomy'     => 'genre',
    'orderby'      => 'name',
    'show_count'   => 0,
    'pad_counts'   => 0,
    'hierarchical' => 1,
    'title_li'     => '',
);
?>
<ul>
    <?php wp_list_categories( $args ); ?>
</ul>

範例 4：只顯示頂層分類、隱藏空分類、顯示文章數

wp_list_categories( array(
    'depth'        => 1,
    'hide_empty'   => 1,
    'show_count'   => 1,
    'title_li'     => '',
    'style'        => 'none', // 不用 ul>li，改用 br 分隔
) );

範例 5：回傳字串供進一步處理

$cats_html = wp_list_categories( array(
    'echo'         => 0,
    'style'        => 'list',
    'title_li'     => '',
    'hierarchical' => false,
) );
// 可對 $cats_html 進行字串替換、正則處理後再輸出
echo $cats_html;

常見陷阱與避坑指南

1. 忘記 title_li=''：預設會輸出「分類」標題 li，導致結構多一層，客製化版面時通常需設為空字串
2. hide_empty 預設為真：新建分類尚無文章時不會顯示，測試時記得設 hide_empty=0
3. exclude vs exclude_tree：前者只排除指定 ID，後者連同所有子孫一併排除，依需求選擇
4. current_category 僅加類別：不會自動高亮，需搭配 CSS 針對 .current-cat 設定樣式
5. walker 物件需實例化：傳入 new My_Category_Walker() 而非類別名稱

效能考量

• 函數內部使用 get_terms() 取得分類資料，預設快取機制下效能良好
• 大型網站（分類數千以上）建議搭配物件快取或片段快取
• 避免在迴圈中重複呼叫，單頁面僅呼叫一次並重用結果

熟練運用 wp_list_categories() 的豐富參數，能精準掌控分類列表的輸出結構與內容，是 WordPress 主題開發者的核心技能之一。