云策 WordPress 开发者社区

类文档

Walker_Category_Checklist

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

概述

Walker_Category_Checklist 是 WordPress 核心的 Walker 类，用于生成分类复选框输入元素的无序列表。它扩展自 Walker 类，主要用于 wp_category_checklist() 和 wp_terms_checklist() 函数。

关键要点

  • 继承自 Walker 类，专用于处理分类（category）或自定义分类法的复选框列表输出。
  • 定义了四个核心方法：start_lvl、end_lvl、start_el 和 end_el，分别控制列表层级和元素的开始与结束。
  • 支持通过参数（如 $args）自定义输出，包括选中的分类、禁用状态、仅列表模式等。
  • 类属性 $tree_type 设置为 'category'，$db_fields 定义了数据库字段映射。
  • 与 wp_terms_checklist() 函数紧密集成，用于生成前端复选框 HTML。

代码示例

public function start_el( &$output, $data_object, $depth = 0, $args = array(), $current_object_id = 0 ) {
    // 示例代码：生成复选框或列表项，根据参数处理选中和禁用状态
    $category = $data_object;
    $taxonomy = $args['taxonomy'] ?? 'category';
    $name = ( 'category' === $taxonomy ) ? 'post_category' : 'tax_input[' . $taxonomy . ']';
    $is_selected = in_array( $category->term_id, $args['selected_cats'] ?? array(), true );
    $is_disabled = ! empty( $args['disabled'] );
    // 输出 HTML 代码
}

注意事项

  • 从 WordPress 5.9.0 开始，方法参数名更新为 $data_object 和 $current_object_id 以支持 PHP 8 命名参数，但内部仍使用 $category 变量保持兼容性。
  • 使用 wp_unique_prefixed_id() 生成唯一的 HTML ID，避免前端冲突。
  • 输出内容通过引用传递（&$output），直接修改输出字符串。
📄 原文内容

Core walker class to output an unordered list of category checkbox input elements.

Description

See also

Methods

Name Description
Walker_Category_Checklist::end_el Ends the element output, if needed.
Walker_Category_Checklist::end_lvl Ends the list of after the elements are added.
Walker_Category_Checklist::start_el Start the element output.
Walker_Category_Checklist::start_lvl Starts the list before the elements are added.

Source

class Walker_Category_Checklist extends Walker {
	public $tree_type = 'category';
	public $db_fields = array(
		'parent' => 'parent',
		'id'     => 'term_id',
	); // TODO: Decouple this.

	/**
	 * Starts the list before the elements are added.
	 *
	 * @see Walker:start_lvl()
	 *
	 * @since 2.5.1
	 *
	 * @param string $output Used to append additional content (passed by reference).
	 * @param int    $depth  Depth of category. Used for tab indentation.
	 * @param array  $args   An array of arguments. See <a href="https://developer.wordpress.org/reference/functions/wp_terms_checklist/">wp_terms_checklist()</a>.
	 */
	public function start_lvl( &$output, $depth = 0, $args = array() ) {
		$indent  = str_repeat( "t", $depth );
		$output .= "$indent<ul class='children'>n";
	}

	/**
	 * Ends the list of after the elements are added.
	 *
	 * @see Walker::end_lvl()
	 *
	 * @since 2.5.1
	 *
	 * @param string $output Used to append additional content (passed by reference).
	 * @param int    $depth  Depth of category. Used for tab indentation.
	 * @param array  $args   An array of arguments. See <a href="https://developer.wordpress.org/reference/functions/wp_terms_checklist/">wp_terms_checklist()</a>.
	 */
	public function end_lvl( &$output, $depth = 0, $args = array() ) {
		$indent  = str_repeat( "t", $depth );
		$output .= "$indent</ul>n";
	}

	/**
	 * Start the element output.
	 *
	 * @see Walker::start_el()
	 *
	 * @since 2.5.1
	 * @since 5.9.0 Renamed `$category` to `$data_object` and `$id` to `$current_object_id`
	 *              to match parent class for PHP 8 named parameter support.
	 *
	 * @param string  $output            Used to append additional content (passed by reference).
	 * @param WP_Term $data_object       The current term object.
	 * @param int     $depth             Depth of the term in reference to parents. Default 0.
	 * @param array   $args              An array of arguments. See <a href="https://developer.wordpress.org/reference/functions/wp_terms_checklist/">wp_terms_checklist()</a>.
	 * @param int     $current_object_id Optional. ID of the current term. Default 0.
	 */
	public function start_el( &$output, $data_object, $depth = 0, $args = array(), $current_object_id = 0 ) {
		// Restores the more descriptive, specific name for use within this method.
		$category = $data_object;

		if ( empty( $args['taxonomy'] ) ) {
			$taxonomy = 'category';
		} else {
			$taxonomy = $args['taxonomy'];
		}

		if ( 'category' === $taxonomy ) {
			$name = 'post_category';
		} else {
			$name = 'tax_input[' . $taxonomy . ']';
		}

		$args['popular_cats'] = ! empty( $args['popular_cats'] ) ? array_map( 'intval', $args['popular_cats'] ) : array();

		$class = in_array( $category->term_id, $args['popular_cats'], true ) ? ' class="popular-category"' : '';

		$args['selected_cats'] = ! empty( $args['selected_cats'] ) ? array_map( 'intval', $args['selected_cats'] ) : array();

		if ( ! empty( $args['list_only'] ) ) {
			$aria_checked = 'false';
			$inner_class  = 'category';

			if ( in_array( $category->term_id, $args['selected_cats'], true ) ) {
				$inner_class .= ' selected';
				$aria_checked = 'true';
			}

			$output .= "n" . '<li' . $class . '>' .
				'<div class="' . $inner_class . '" data-term-id=' . $category->term_id .
				' tabindex="0" role="checkbox" aria-checked="' . $aria_checked . '">' .
				/** This filter is documented in wp-includes/category-template.php */
				esc_html( apply_filters( 'the_category', $category->name, '', '' ) ) . '</div>';
		} else {
			$is_selected         = in_array( $category->term_id, $args['selected_cats'], true );
			$is_disabled         = ! empty( $args['disabled'] );
			$li_element_id       = wp_unique_prefixed_id( "in-{$taxonomy}-{$category->term_id}-" );
			$checkbox_element_id = wp_unique_prefixed_id( "in-{$taxonomy}-{$category->term_id}-" );

			$output .= "n<li id='" . esc_attr( $li_element_id ) . "'$class>" .
				'<label class="selectit"><input value="' . $category->term_id . '" type="checkbox" name="' . $name . '[]" id="' . esc_attr( $checkbox_element_id ) . '"' .
				checked( $is_selected, true, false ) .
				disabled( $is_disabled, true, false ) . ' /> ' .
				/** This filter is documented in wp-includes/category-template.php */
				esc_html( apply_filters( 'the_category', $category->name, '', '' ) ) . '</label>';
		}
	}

	/**
	 * Ends the element output, if needed.
	 *
	 * @see Walker::end_el()
	 *
	 * @since 2.5.1
	 * @since 5.9.0 Renamed `$category` to `$data_object` to match parent class for PHP 8 named parameter support.
	 *
	 * @param string  $output      Used to append additional content (passed by reference).
	 * @param WP_Term $data_object The current term object.
	 * @param int     $depth       Depth of the term in reference to parents. Default 0.
	 * @param array   $args        An array of arguments. See <a href="https://developer.wordpress.org/reference/functions/wp_terms_checklist/">wp_terms_checklist()</a>.
	 */
	public function end_el( &$output, $data_object, $depth = 0, $args = array() ) {
		$output .= "</li>n";
	}
}

View all references View on Trac View on GitHub

Uses Description
Walkerwp-includes/class-wp-walker.php

A class for displaying various tree-like structures.

Changelog

Version Description
2.5.1 Introduced.