Question

wp_terms_checklist( int $post_id,  array|string $args = array() )

Output an unordered list of checkbox input elements labelled with term names.

---

description

Taxonomy-independent version of wp_category_checklist().

---

参数

$post_id

(int) (Optional) Post ID. Default 0.

$args

(array|string) (Optional) Array or string of arguments for generating a terms checklist.

• 'descendants_and_self'
  (int) ID of the category to output along with its descendants. Default 0.
• 'selected_cats'
  (array) List of categories to mark as checked. Default false.
• 'popular_cats'
  (array) List of categories to receive the "popular-category" class. Default false.
• 'walker'
  (object) Walker object to use to build the output. Default is a Walker_Category_Checklist instance.
• 'taxonomy'
  (string) Taxonomy to generate the checklist for. Default 'category'.
• 'checked_ontop'
  (bool) Whether to move checked items out of the hierarchy and to the top of the list. Default true.
• 'echo'
  (bool) Whether to echo the generated markup. False to return the markup instead of echoing it. Default true.

Default value: array()

---

源代码

File: wp-admin/includes/template.php

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

	/**
	 * Filters the taxonomy terms checklist arguments.
	 *
	 * @since 3.4.0
	 *
	 * @see wp_terms_checklist()
	 *
	 * @param array $args    An array of arguments.
	 * @param int   $post_id The post ID.
	 */
	$params = apply_filters( 'wp_terms_checklist_args', $args, $post_id );

	$r = wp_parse_args( $params, $defaults );

	if ( empty( $r['walker'] ) || ! ( $r['walker'] instanceof Walker ) ) {
		$walker = new Walker_Category_Checklist;
	} else {
		$walker = $r['walker'];
	}

	$taxonomy = $r['taxonomy'];
	$descendants_and_self = (int) $r['descendants_and_self'];

	$args = array( 'taxonomy' => $taxonomy );

	$tax = get_taxonomy( $taxonomy );
	$args['disabled'] = ! current_user_can( $tax->cap->assign_terms );

	$args['list_only'] = ! empty( $r['list_only'] );

	if ( is_array( $r['selected_cats'] ) ) {
		$args['selected_cats'] = $r['selected_cats'];
	} elseif ( $post_id ) {
		$args['selected_cats'] = wp_get_object_terms( $post_id, $taxonomy, array_merge( $args, array( 'fields' => 'ids' ) ) );
	} else {
		$args['selected_cats'] = array();
	}
	if ( is_array( $r['popular_cats'] ) ) {
		$args['popular_cats'] = $r['popular_cats'];
	} else {
		$args['popular_cats'] = get_terms( $taxonomy, array(
			'fields' => 'ids',
			'orderby' => 'count',
			'order' => 'DESC',
			'number' => 10,
			'hierarchical' => false
		) );
	}
	if ( $descendants_and_self ) {
		$categories = (array) get_terms( $taxonomy, array(
			'child_of' => $descendants_and_self,
			'hierarchical' => 0,
			'hide_empty' => 0
		) );
		$self = get_term( $descendants_and_self, $taxonomy );
		array_unshift( $categories, $self );
	} else {
		$categories = (array) get_terms( $taxonomy, array( 'get' => 'all' ) );
	}

	$output = '';

	if ( $r['checked_ontop'] ) {
		// Post process $categories rather than adding an exclude to the get_terms() query to keep the query the same across all posts (for any query cache)
		$checked_categories = array();
		$keys = array_keys( $categories );

		foreach ( $keys as $k ) {
			if ( in_array( $categories[$k]->term_id, $args['selected_cats'] ) ) {
				$checked_categories[] = $categories[$k];
				unset( $categories[$k] );
			}
		}

		// Put checked cats on top
		$output .= call_user_func_array( array( $walker, 'walk' ), array( $checked_categories, 0, $args ) );
	}
	// Then the rest of them
	$output .= call_user_func_array( array( $walker, 'walk' ), array( $categories, 0, $args ) );

	if ( $r['echo'] ) {
		echo $output;
	}

	return $output;
}

---

更新日志

Version	description
4.4.0	Introduced the $echo argument.
3.0.0	Introduced.

---

相关函数

Uses

• wp-admin/includes/template.php: wp_terms_checklist_args
• wp-includes/capabilities.php: current_user_can()
• wp-includes/functions.php: wp_parse_args()
• wp-includes/taxonomy.php: wp_get_object_terms()
• wp-includes/taxonomy.php: get_terms()
• wp-includes/taxonomy.php: get_taxonomy()
• wp-includes/taxonomy.php: get_term()
• wp-includes/plugin.php: apply_filters()
Show 3 more uses Hide more uses

---

Used By

• wp-admin/includes/class-wp-press-this.php: WP_Press_This::categories_html()
• wp-admin/includes/template.php: wp_category_checklist()
• wp-admin/includes/ajax-actions.php: _wp_ajax_add_hierarchical_term()
• wp-admin/includes/meta-boxes.php: post_categories_meta_box()
• wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::inline_edit()

---

User Contributed Notes