Question

wp_dropdown_pages( array|string $args = '' )

Retrieve or display list of pages as a dropdown (select list).

---

description

---

参数

$args

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

• 'depth'
  (int) Maximum depth. Default 0.
• 'child_of'
  (int) Page ID to retrieve child pages of. Default 0.
• 'selected'
  (int|string) Value of the option that should be selected. Default 0.
• 'echo'
  (bool|int) Whether to echo or return the generated markup. Accepts 0, 1, or their bool equivalents. Default 1.
• 'name'
  (string) Value for the 'name' attribute of the select element. Default 'page_id'.
• 'id'
  (string) Value for the 'id' attribute of the select element.
• 'class'
  (string) Value for the 'class' attribute of the select element. Default: none. Defaults to the value of $name.
• 'show_option_none'
  (string) Text to display for showing no pages. Default empty (does not display).
• 'show_option_no_change'
  (string) Text to display for "no change" option. Default empty (does not display).
• 'option_none_value'
  (string) Value to use when no page is selected.
• 'value_field'
  (string) Post field used to populate the 'value' attribute of the option elements. Accepts any valid post field. Default 'ID'.

Default value: ''

---

返回值

(string) HTML content, if not displaying.

---

源代码

File: wp-includes/post-template.php

function wp_dropdown_pages( $args = '' ) {
	$defaults = array(
		'depth' => 0, 'child_of' => 0,
		'selected' => 0, 'echo' => 1,
		'name' => 'page_id', 'id' => '',
		'class' => '',
		'show_option_none' => '', 'show_option_no_change' => '',
		'option_none_value' => '',
		'value_field' => 'ID',
	);

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

	$pages = get_pages( $r );
	$output = '';
	// Back-compat with old system where both id and name were based on $name argument
	if ( empty( $r['id'] ) ) {
		$r['id'] = $r['name'];
	}

	if ( ! empty( $pages ) ) {
		$class = '';
		if ( ! empty( $r['class'] ) ) {
			$class = " class='" . esc_attr( $r['class'] ) . "'";
		}

		$output = "<select name='" . esc_attr( $r['name'] ) . "'" . $class . " id='" . esc_attr( $r['id'] ) . "'>\n";
		if ( $r['show_option_no_change'] ) {
			$output .= "\t<option value=\"-1\">" . $r['show_option_no_change'] . "</option>\n";
		}
		if ( $r['show_option_none'] ) {
			$output .= "\t<option value=\"" . esc_attr( $r['option_none_value'] ) . '">' . $r['show_option_none'] . "</option>\n";
		}
		$output .= walk_page_dropdown_tree( $pages, $r['depth'], $r );
		$output .= "</select>\n";
	}

	/**
	 * Filters the HTML output of a list of pages as a drop down.
	 *
	 * @since 2.1.0
	 * @since 4.4.0 `$r` and `$pages` added as arguments.
	 *
	 * @param string $output HTML output for drop down list of pages.
	 * @param array  $r      The parsed arguments array.
	 * @param array  $pages  List of WP_Post objects returned by `get_pages()`
 	 */
	$html = apply_filters( 'wp_dropdown_pages', $output, $r, $pages );

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

---

更新日志

Version	description
4.3.0	The $class argument was added.
4.2.0	The $value_field argument was added.
2.1.0	Introduced.

---

相关函数

Uses

• wp-includes/formatting.php: esc_attr()
• wp-includes/functions.php: wp_parse_args()
• wp-includes/plugin.php: apply_filters()
• wp-includes/post-template.php: walk_page_dropdown_tree()
• wp-includes/post-template.php: wp_dropdown_pages
• wp-includes/post.php: get_pages()
Show 1 more use Hide more uses

---

Used By

• wp-admin/includes/meta-boxes.php: page_attributes_meta_box()
• wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::inline_edit()
• wp-includes/class-wp-customize-control.php: WP_Customize_Control::render_content()

---

User Contributed Notes

1. Skip to note content 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 Contributed by Codex

   Dropdown with submit button
   Displays a hierarchical page dropdown list in HTML form with a submit button.

   
   <li id="pages">
   	<h2><?php _e('pages:'); ?></h2>
   	<form action="<?php bloginfo('url'); ?>" method="get">
   		<?php wp_dropdown_pages(); ?>
   		<input type="submit" name="submit" value="view" />
   	</form>
   </li>
   
   

In addition, $args can include ‘sort_column’ and other get_pages() parameters, as shown in the page_attributes_meta_box() 源代码 code:

    $dropdown_args = array(
            'post_type'        => $post->post_type,
            'exclude_tree'     => $post->ID,
            'selected'         => $post->post_parent,
            'name'             => 'parent_id',
            'show_option_none' => __('(no parent)'),
            'sort_column'      => 'menu_order, post_title',
            'echo'             => 0,
        );
    ...
    $pages = wp_dropdown_pages( $dropdown_args );