云策 WordPress 开发者社区

函数文档

wp_category_checklist()

查看官方原文 ↗
💡 云策文档标注

概述

wp_category_checklist() 是 WordPress 核心函数，用于输出一个包含分类复选框的无序列表，常用于后台文章编辑界面。该函数基于 wp_terms_checklist() 实现，专门处理“category”分类法。

关键要点

  • 函数输出一个无序列表（
      ），其中每个列表项（
    • ）包含一个复选框（），标签为分类名称。
    • 主要参数包括 $post_id（文章ID）、$descendants_and_self（分类ID及其子类）、$selected_cats（预选分类数组）、$popular_cats（热门分类数组）、$walker（Walker对象）和 $checked_ontop（是否将选中项置顶）。
    • 函数内部调用 wp_terms_checklist()，通过传递参数数组来指定分类法为“category”。
    • 注意：$post_id 和 $selected_cats 不应同时使用，以避免冲突。
    • 自 WordPress 2.5.1 版本引入，相关函数包括 wp_terms_checklist() 和已弃用的 dropdown_categories()。

    代码示例

    // 输出所有分类的复选框列表
wp_category_checklist();

// 输出特定分类及其子类的复选框列表
wp_category_checklist( 0, $category_id = 22 );

// 为指定文章预选所有分类
wp_category_checklist( $post_id = 45 );

// 预选指定分类数组
$selected_cats = array( 45, 33, 118 );
wp_category_checklist( 0, 0, $selected_cats );

// 指定热门分类数组
$popular = array( 45, 33, 118 );
wp_category_checklist( 0, 0, false, $popular );

// 使用自定义 Walker 对象
$walker = new My_Walker_Category_Checklist();
wp_category_checklist( 0, 0, false, false, $walker );

// 将选中项置顶
$selected_cats = array( 45, 33, 118 );
$checked_ontop = true;
wp_category_checklist( 0, 0, $selected_cats, false, null, $checked_ontop );

    注意事项

    • 参数 $post_id 和 $selected_cats 不应同时使用，因为 $post_id 会自动从文章获取分类，而 $selected_cats 会手动指定，可能导致不一致。
    • 函数默认使用 Walker_Category_Checklist 作为 Walker 对象，可通过 $walker 参数自定义以改变输出结构。
    • $checked_ontop 参数默认为 true，会将已选中的分类移到列表顶部，便于用户查看。
📄 原文内容

Outputs an unordered list of checkbox input elements labeled with category names.

Description

See also

Parameters

$post_idintoptional
Post to generate a categories checklist for. Default 0.
$selected_cats must not be an array. Default 0.
$descendants_and_selfintoptional
ID of the category to output along with its descendants.
Default 0.
$selected_catsint[]|falseoptional
Array of category IDs to mark as checked.

Default:false

$popular_catsint[]|falseoptional
Array of category IDs to receive the “popular-category” class.

Default:false

$walkerWalkeroptional
Walker object to use to build the output.
Default is a Walker_Category_Checklist instance.

Default:null

$checked_ontopbooloptional
Whether to move checked items out of the hierarchy and to the top of the list.

Default:true

Source

function wp_category_checklist( $post_id = 0, $descendants_and_self = 0, $selected_cats = false, $popular_cats = false, $walker = null, $checked_ontop = true ) {
	wp_terms_checklist(
		$post_id,
		array(
			'taxonomy'             => 'category',
			'descendants_and_self' => $descendants_and_self,
			'selected_cats'        => $selected_cats,
			'popular_cats'         => $popular_cats,
			'walker'               => $walker,
			'checked_ontop'        => $checked_ontop,
		)
	);
}

View all references View on Trac View on GitHub

Uses Description
wp_terms_checklist()wp-admin/includes/template.php

Outputs an unordered list of checkbox input elements labelled with term names.
Used by Description
dropdown_categories()wp-admin/includes/deprecated.php

Legacy function used to generate the categories checklist control.

Changelog

Version Description
2.5.1 Introduced.

User Contributed Notes

  7. Skip to note 14 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    List the checked categories before the rest

    $selected_cats = array( 45, 33, 118 );
$checked_ontop = true;

wp_category_checklist( 0, 0, $selected_cats, false, null, $checked_ontop );

    You may also use any of the parameters in combination, except for $post_id and $selected_cats, which should not be used together.