Question

wp_dropdown_categories( string|array $args = '' )

Display or retrieve the HTML dropdown list of categories.

---

description

The ‘hierarchical’ argument, which is disabled by default, will override the depth argument, unless it is true. When the argument is false, it will display all of the categories. When it is enabled it will use the value in the ‘depth’ argument.

---

参数

$args

(string|array) (Optional) Array or string of arguments to generate a categories drop-down element.

• 'show_option_all'
  (string) Text to display for showing all categories.
• 'show_option_none'
  (string) Text to display for showing no categories.
• 'option_none_value'
  (string) Value to use when no category is selected.
• 'orderby'
  (string) Which column to use for ordering categories. See get_terms() for a list of accepted values. Default 'id' (term_id).
• 'order'
  (string) Whether to order terms in ascending or descending order. Accepts 'ASC' or 'DESC'. Default 'ASC'.
• 'pad_counts'
  (bool) See get_terms() for an argument description. Default false.
• 'show_count'
  (bool|int) Whether to include post counts. Accepts 0, 1, or their bool equivalents. Default 0.
• 'hide_empty'
  (bool|int) Whether to hide categories that don't have any posts. Accepts 0, 1, or their bool equivalents. Default 1.
• 'child_of'
  (int) Term ID to retrieve child terms of. See get_terms(). Default 0.
• 'exclude'
  (array|string) Array or comma/space-separated string of term ids to exclude. If $include is non-empty, $exclude is ignored. Default empty array.
• 'echo'
  (bool|int) Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.
• 'hierarchical'
  (bool|int) Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool equivalents. Default 0.
• 'depth'
  (int) Maximum depth. Default 0.
• 'tab_index'
  (int) Tab index for the select element. Default 0 (no tabindex).
• 'name'
  (string) Value for the 'name' attribute of the select element. Default 'cat'.
• 'id'
  (string) Value for the 'id' attribute of the select element. Defaults to the value of $name.
• 'class'
  (string) Value for the 'class' attribute of the select element. Default 'postform'.
• 'selected'
  (int|string) Value of the option that should be selected. Default 0.
• 'value_field'
  (string) Term field that should be used to populate the 'value' attribute of the option elements. Accepts any valid term field: 'term_id', 'name', 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description', 'parent', 'count'. Default 'term_id'.
• 'taxonomy'
  (string|array) Name of the category or categories to retrieve. Default 'category'.
• 'hide_if_empty'
  (bool) True to skip generating markup if no categories are found. Default false (create select element even if no categories are found).
• 'required'
  (bool) Whether the <select> element should have the HTML5 'required' attribute. Default false.

Default value: ''

---

返回值

(string) HTML content only if 'echo' argument is 0.

---

源代码

File: wp-includes/category-template.php

function wp_dropdown_categories( $args = '' ) {
	$defaults = array(
		'show_option_all'   => '',
		'show_option_none'  => '',
		'orderby'           => 'id',
		'order'             => 'ASC',
		'show_count'        => 0,
		'hide_empty'        => 1,
		'child_of'          => 0,
		'exclude'           => '',
		'echo'              => 1,
		'selected'          => 0,
		'hierarchical'      => 0,
		'name'              => 'cat',
		'id'                => '',
		'class'             => 'postform',
		'depth'             => 0,
		'tab_index'         => 0,
		'taxonomy'          => 'category',
		'hide_if_empty'     => false,
		'option_none_value' => -1,
		'value_field'       => 'term_id',
		'required'          => false,
	);

	$defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;

	// Back compat.
	if ( isset( $args['type'] ) && 'link' == $args['type'] ) {
		_deprecated_argument( __FUNCTION__, '3.0.0',
			/* translators: 1: "type => link", 2: "taxonomy => link_category" */
			sprintf( __( '%1$s is deprecated. Use %2$s instead.' ),
				'<code>type => link</code>',
				'<code>taxonomy => link_category</code>'
			)
		);
		$args['taxonomy'] = 'link_category';
	}

	$r = wp_parse_args( $args, $defaults );
	$option_none_value = $r['option_none_value'];

	if ( ! isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) {
		$r['pad_counts'] = true;
	}

	$tab_index = $r['tab_index'];

	$tab_index_attribute = '';
	if ( (int) $tab_index > 0 ) {
		$tab_index_attribute = " tabindex=\"$tab_index\"";
	}

	// Avoid clashes with the 'name' param of get_terms().
	$get_terms_args = $r;
	unset( $get_terms_args['name'] );
	$categories = get_terms( $r['taxonomy'], $get_terms_args );

	$name = esc_attr( $r['name'] );
	$class = esc_attr( $r['class'] );
	$id = $r['id'] ? esc_attr( $r['id'] ) : $name;
	$required = $r['required'] ? 'required' : '';

	if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) {
		$output = "<select $required name='$name' id='$id' class='$class' $tab_index_attribute>\n";
	} else {
		$output = '';
	}
	if ( empty( $categories ) && ! $r['hide_if_empty'] && ! empty( $r['show_option_none'] ) ) {

		/**
		 * Filters a taxonomy drop-down display element.
		 *
		 * A variety of taxonomy drop-down display elements can be modified
		 * just prior to display via this filter. Filterable arguments include
		 * 'show_option_none', 'show_option_all', and various forms of the
		 * term name.
		 *
		 * @since 1.2.0
		 *
		 * @see wp_dropdown_categories()
		 *
		 * @param string $element Taxonomy element to list.
		 */
		$show_option_none = apply_filters( 'list_cats', $r['show_option_none'] );
		$output .= "\t<option value='" . esc_attr( $option_none_value ) . "' selected='selected'>$show_option_none</option>\n";
	}

	if ( ! empty( $categories ) ) {

		if ( $r['show_option_all'] ) {

			/** This filter is documented in wp-includes/category-template.php */
			$show_option_all = apply_filters( 'list_cats', $r['show_option_all'] );
			$selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
			$output .= "\t<option value='0'$selected>$show_option_all</option>\n";
		}

		if ( $r['show_option_none'] ) {

			/** This filter is documented in wp-includes/category-template.php */
			$show_option_none = apply_filters( 'list_cats', $r['show_option_none'] );
			$selected = selected( $option_none_value, $r['selected'], false );
			$output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$selected>$show_option_none</option>\n";
		}

		if ( $r['hierarchical'] ) {
			$depth = $r['depth'];  // Walk the full depth.
		} else {
			$depth = -1; // Flat.
		}
		$output .= walk_category_dropdown_tree( $categories, $depth, $r );
	}

	if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) {
		$output .= "</select>\n";
	}
	/**
	 * Filters the taxonomy drop-down output.
	 *
	 * @since 2.1.0
	 *
	 * @param string $output HTML output.
	 * @param array  $r      Arguments used to build the drop-down.
	 */
	$output = apply_filters( 'wp_dropdown_cats', $output, $r );

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

---

更新日志

Version	description
4.6.0	Introduced the required argument.
4.2.0	Introduced the value_field argument.
2.1.0	Introduced.

---

相关函数

Uses

• wp-includes/category-template.php: walk_category_dropdown_tree()
• wp-includes/category-template.php: list_cats
• wp-includes/category-template.php: wp_dropdown_cats
• wp-includes/l10n.php: __()
• wp-includes/formatting.php: esc_attr()
• wp-includes/general-template.php: selected()
• wp-includes/query.php: is_category()
• wp-includes/query.php: get_query_var()
• wp-includes/functions.php: _deprecated_argument()
• wp-includes/functions.php: wp_parse_args()
• wp-includes/taxonomy.php: get_terms()
• wp-includes/plugin.php: apply_filters()
Show 7 more uses Hide more uses

---

Used By

• wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::categories_dropdown()
• wp-admin/includes/class-wp-press-this.php: WP_Press_This::categories_html()
• wp-admin/includes/class-wp-links-list-table.php: WP_Links_List_Table::extra_tablenav()
• wp-admin/includes/ajax-actions.php: _wp_ajax_add_hierarchical_term()
• wp-admin/includes/meta-boxes.php: post_categories_meta_box()
• wp-includes/deprecated.php: dropdown_cats()
• wp-includes/widgets/class-wp-widget-categories.php: WP_Widget_Categories::widget()
Show 2 more used by Hide more used by

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note Contributed by ayandebnath

   You can use Walker with this wp_dropdown_categories function.

   Example –

   
   class Walker_custom_CategoryDropdown extends Walker_CategoryDropdown {
   
   	public function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) {
   		$pad = str_repeat(' ', $depth * 3);
    
   		/** This filter is documented in wp-includes/category-template.php */
   		$cat_name = apply_filters( 'list_cats', $category->name, $category );
    
   		if ( isset( $args['value_field'] ) && isset( $category->{$args['value_field']} ) ) {
   			$value_field = $args['value_field'];
   		} else {
   			$value_field = 'term_id';
   		}
    
   		$output .= "\t<option class=\"level-$depth\" value=\"" . esc_attr( $category->{$value_field} ) . "\"";
    
   		// Type-juggling causes false matches, so we force everything to a string.
   		if ( (string) $category->{$value_field} === (string) $args['selected'] )
   			$output .= ' selected="selected"';
   		
   		$output .= ' data-uri="'.get_term_link($category).'" '; /* Custom */
   		
   		$output .= '>';
   		$output .= $pad.$cat_name;
   		if ( $args['show_count'] )
   			$output .= '&nbsp;&nbsp;('. number_format_i18n( $category->count ) .')';
   		$output .= "</option>\n";
   	}
   }
   
   $cat_arg=array(
   	'taxonomy'=> 'category',
   	'class' => 'form-control',
   	'value_field' => 'term_id',
   	'selected' => $taxonomy_id,
   	
   	'orderby' => 'name',
   	'show_count' => 0,
   	'hierarchical' => true,
   	'hide_if_empty' => true,
   	
   	'walker'  => new Walker_custom_CategoryDropdown()
   );
   

Displays a hierarchical category dropdown list in an HTML select form with a submit button, with a count of posts in each category.

<h2><?php _e( 'Categories:', 'textdomain' ); ?></h2>
<form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">
	<?php wp_dropdown_categories( 'show_count=1&hierarchical=1' ); ?>
	<input type="submit" name="submit" value="view" />
</form>

This example displays a category dropdown list using JavaScript instead of a submit button, with a no-selection option (labeled: “Select category”):

<h2><?php _e( 'Posts by Category', 'textdomain' ); ?></h2>
	<?php wp_dropdown_categories( 'show_option_none=Select category' ); ?>
<script type="text/javascript">
	<!--
	var dropdown = document.getElementById("cat");
	function onCatChange() {
		if ( dropdown.options[dropdown.selectedIndex].value > 0 ) {
			location.href = "<?php echo esc_url( home_url( '/' ) ); ?>?cat="+dropdown.options[dropdown.selectedIndex].value;
		}
	}
	dropdown.onchange = onCatChange;
	-->
</script>

In this example the echo parameter (echo=0) is used. A simple preg_replace inserts the JavaScript code. It even works without JavaScript (submit button is wrapped by noscript tags).

<h2><?php _e( 'Posts by Category', 'textdomain' ); ?></h2>
<form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">

	<?php
	$args = array(
		'show_option_none' => __( 'Select category', 'textdomain' ),
		'show_count'       => 1,
		'orderby'          => 'name',
		'echo'             => 0,
	);
	?>

	<?php $select  = wp_dropdown_categories( $args ); ?>
	<?php $replace = "<select$1 onchange='return this.form.submit()'>"; ?>
	<?php $select  = preg_replace( '#<select([^>]*)>#', $replace, $select ); ?>

	<?php echo $select; ?>

	<noscript>
		<input type="submit" value="View" />
	</noscript>

</form>

By default, wp_dropdown_categories only returns categories that have been assigned to at least one post. To override this set the hide_empty parameter to false ("0").

<?php wp_dropdown_categories( 'hide_empty=0' ); ?>