wp_dropdown_pages()

💡 云策文档标注

概述

wp_dropdown_pages() 函数用于检索或显示页面列表作为下拉选择框（select 列表）。它基于 get_pages() 函数构建，支持丰富的参数配置，适用于 WordPress 开发中的页面选择场景。

关键要点

函数返回或输出 HTML 下拉列表，可通过 echo 参数控制输出方式。
参数包括深度控制、子页面筛选、选中项设置、HTML 属性（如 name、id、class）等。
支持从 get_pages() 继承的参数，如排序、层级、排除/包含页面、元数据过滤等。
提供 show_option_none 和 show_option_no_change 选项，用于自定义无页面或“无变化”时的显示文本。
使用 wp_dropdown_pages 过滤器可自定义 HTML 输出。

代码示例

// 基本用法：显示页面下拉列表
wp_dropdown_pages( array(
    'name' => 'page_id',
    'selected' => 5,
    'echo' => 1
) );

// 高级用法：结合 get_pages() 参数
$dropdown_args = array(
    'post_type' => 'page',
    'sort_column' => 'menu_order, post_title',
    'show_option_none' => '选择页面',
    'echo' => 0
);
$pages = wp_dropdown_pages( $dropdown_args );

注意事项

对于自定义文章类型，需在 register_post_type 时设置 'hierarchical' => true 以使下拉列表正常工作。
参数 $value_field 控制选项的 value 属性，默认为 'ID'，可更改为其他文章字段。
使用过滤器 wp_dropdown_pages 可修改输出，例如实现多选功能。

📄 原文内容

Retrieves or displays a list of pages as a dropdown (select list).

Description

Parameters

$argsarray|stringoptional

Array or string of arguments to generate a page dropdown. See get_pages() for additional arguments.

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. Default empty.
value_field string
Post field used to populate the 'value' attribute of the option elements. Accepts any valid post field. Default 'ID'.

More Arguments from get_pages( … $args )

Array or string of arguments to retrieve pages.

child_of int
Page ID to return child and grandchild pages of. Note: The value of $hierarchical has no bearing on whether $child_of returns hierarchical results. Default 0, or no restriction.
sort_order string
How to sort retrieved pages. Accepts 'ASC', 'DESC'. Default 'ASC'.
sort_column string
What columns to sort pages by, comma-separated. Accepts 'post_author', 'post_date', 'post_title', 'post_name', 'post_modified', 'menu_order', 'post_modified_gmt', 'post_parent', 'ID', 'rand', 'comment*count'.
'post*' can be omitted for any values that start with it.
Default 'post_title'.
hierarchical bool
Whether to return pages hierarchically. If false in conjunction with $child_of also being false, both arguments will be disregarded.
Default true.
exclude int[]
Array of page IDs to exclude.
include int[]
Array of page IDs to include. Cannot be used with $child_of, $parent, $exclude, $meta_key, $meta_value, or $hierarchical.
meta_key string
Only include pages with this meta key.
meta_value string
Only include pages with this meta value. Requires $meta_key.
authors string
A comma-separated list of author IDs.
parent int
Page ID to return direct children of. Default -1, or no restriction.
exclude_tree string|int[]
Comma-separated string or array of page IDs to exclude.
number int
The number of pages to return. Default 0, or all pages.
offset int
The number of pages to skip before returning. Requires $number.
Default 0.
post_type string
The post type to query. Default 'page'.
post_status string|array
A comma-separated list or array of post statuses to include.
Default 'publish'.

Return

string HTML dropdown list of pages.

Source

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',
	);

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

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

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

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

	/**
	 * Filters the HTML output of a list of pages as a dropdown.
	 *
	 * @since 2.1.0
	 * @since 4.4.0 `$parsed_args` and `$pages` added as arguments.
	 *
	 * @param string    $output      HTML output for dropdown list of pages.
	 * @param array     $parsed_args The parsed arguments array. See wp_dropdown_pages()
	 *                               for information on accepted arguments.
	 * @param WP_Post[] $pages       Array of the page objects.
	 */
	$html = apply_filters( 'wp_dropdown_pages', $output, $parsed_args, $pages );

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

	return $html;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_dropdown_pages’, string $output, array $parsed_args, WP_Post[] $pages ): Filters the HTML output of a list of pages as a dropdown.

Uses	Description
walk_page_dropdown_tree()`wp-includes/post-template.php`	Retrieves HTML dropdown (select) content for page list.
get_pages()`wp-includes/post.php`	Retrieves an array of pages (or hierarchical post type items).
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 3 more Show less

Used by	Description
page_attributes_meta_box()`wp-admin/includes/meta-boxes.php`	Displays page attributes form fields.
WP_Posts_List_Table::inline_edit()`wp-admin/includes/class-wp-posts-list-table.php`	Outputs the hidden row displayed when inline editing
WP_Customize_Control::render_content()`wp-includes/class-wp-customize-control.php`	Renders the control’s content.

Changelog

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

User Contributed Notes

Skip to note 5 content

John Dorner

6 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
For this to work for custom post types, you must set
```
'hierarchical' => true
```
in the custom post type’s settings when you register_post_type that you are getting the dropdown for.
If you don’t want the custom post type to truly be hierarchical, ensure the 'supports' arg doesn’t include 'page-attributes'
Log in to add feedback
Skip to note 6 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Dropdown with submit button
Displays a hierarchical page dropdown list in HTML form with a submit button.
```
<li id="pages">
	<h2></h2>
	<form action="<?php bloginfo('url'); ?>" method="get">
		
		<input type="submit" name="submit" value="view" />
	</form>
</li>
```
Log in to add feedback
Skip to note 7 content

Sachyya

6 years ago

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
Make dropdown list multiple select
This is useful when you want to make multiple select or using with select2.js kinda things.
```
add_filter( 'wp_dropdown_pages', 'wporg_domain_make_multiple_select_pages' );
function wporg_domain_make_multiple_select_pages( $output ) {
	return str_replace( '<select ', '<select multiple="multiple" ', $output );
}
```
Log in to add feedback

Skip to note 8 content

jon

10 years ago

In addition, $args can include ‘sort_column’ and other get_pages() parameters, as shown in the page_attributes_meta_box() source 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 );

to make “post_type” work you have to set “hierarchical” to true at the custom post type creation args

The Three 6 years ago

云策 WordPress 开发者社区

函数文档