get_pages()

💡 云策文档标注

概述

get_pages() 函数用于检索页面或分层文章类型的数组，基于 WP_Query 实现，支持多种参数进行筛选和排序。返回 WP_Post 对象数组或 false。

关键要点

核心功能：检索页面或分层文章类型（如页面）的数组，默认查询 'page' 文章类型。
参数详解：支持 child_of、sort_order、sort_column、hierarchical、exclude、include、meta_key、meta_value、authors、parent、exclude_tree、number、offset、post_type、post_status 等参数，用于精确控制查询结果。
返回值：成功时返回 WP_Post 对象数组，失败时返回 false（例如文章类型非分层或状态不支持）。
内部机制：使用 WP_Query 构建查询，支持过滤器 get_pages_query_args 和 get_pages 进行自定义。
注意事项：include 参数会覆盖 child_of、parent、exclude、meta_key、meta_value 和 hierarchical；post_status 不支持 'any' 值。

代码示例

// 示例：获取所有页面并显示为下拉列表
$pages = get_pages();
foreach ( $pages as $page ) {
    echo '<option value="' . $page->ID . '">' . $page->post_title . '</option>';
}

注意事项

使用 include 参数时，会忽略 child_of、parent、exclude、meta_key、meta_value 和 hierarchical 参数。
post_status 参数不能使用 'any'，否则可能导致无结果返回。
函数要求查询的文章类型必须是分层的，否则返回 false。

📄 原文内容

Retrieves an array of pages (or hierarchical post type items).

Parameters

$argsarray|stringoptional

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'.

Default:array()

Return

WP_Post[]|false Array of pages (or hierarchical post type items). Boolean false if the specified post type is not hierarchical or the specified status is not supported by the post type.

Source

function get_pages( $args = array() ) {
	$defaults = array(
		'child_of'     => 0,
		'sort_order'   => 'ASC',
		'sort_column'  => 'post_title',
		'hierarchical' => 1,
		'exclude'      => array(),
		'include'      => array(),
		'meta_key'     => '',
		'meta_value'   => '',
		'authors'      => '',
		'parent'       => -1,
		'exclude_tree' => array(),
		'number'       => '',
		'offset'       => 0,
		'post_type'    => 'page',
		'post_status'  => 'publish',
	);

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

	$number       = (int) $parsed_args['number'];
	$offset       = (int) $parsed_args['offset'];
	$child_of     = (int) $parsed_args['child_of'];
	$hierarchical = $parsed_args['hierarchical'];
	$exclude      = $parsed_args['exclude'];
	$meta_key     = $parsed_args['meta_key'];
	$meta_value   = $parsed_args['meta_value'];
	$parent       = $parsed_args['parent'];
	$post_status  = $parsed_args['post_status'];

	// Make sure the post type is hierarchical.
	$hierarchical_post_types = get_post_types( array( 'hierarchical' => true ) );
	if ( ! in_array( $parsed_args['post_type'], $hierarchical_post_types, true ) ) {
		return false;
	}

	if ( $parent > 0 && ! $child_of ) {
		$hierarchical = false;
	}

	// Make sure we have a valid post status.
	if ( ! is_array( $post_status ) ) {
		$post_status = explode( ',', $post_status );
	}
	if ( array_diff( $post_status, get_post_stati() ) ) {
		return false;
	}

	$query_args = array(
		'orderby'                => 'post_title',
		'order'                  => 'ASC',
		'post__not_in'           => wp_parse_id_list( $exclude ),
		'meta_key'               => $meta_key,
		'meta_value'             => $meta_value,
		'posts_per_page'         => -1,
		'offset'                 => $offset,
		'post_type'              => $parsed_args['post_type'],
		'post_status'            => $post_status,
		'update_post_term_cache' => false,
		'update_post_meta_cache' => false,
		'ignore_sticky_posts'    => true,
		'no_found_rows'          => true,
	);

	if ( ! empty( $parsed_args['include'] ) ) {
		$child_of = 0; // Ignore child_of, parent, exclude, meta_key, and meta_value params if using include.
		$parent   = -1;
		unset( $query_args['post__not_in'], $query_args['meta_key'], $query_args['meta_value'] );
		$hierarchical           = false;
		$query_args['post__in'] = wp_parse_id_list( $parsed_args['include'] );
	}

	if ( ! empty( $parsed_args['authors'] ) ) {
		$post_authors = wp_parse_list( $parsed_args['authors'] );

		if ( ! empty( $post_authors ) ) {
			$query_args['author__in'] = array();
			foreach ( $post_authors as $post_author ) {
				// Do we have an author id or an author login?
				if ( 0 === (int) $post_author ) {
					$post_author = get_user_by( 'login', $post_author );
					if ( empty( $post_author ) ) {
						continue;
					}
					if ( empty( $post_author->ID ) ) {
						continue;
					}
					$post_author = $post_author->ID;
				}
				$query_args['author__in'][] = (int) $post_author;
			}
		}
	}

	if ( is_array( $parent ) ) {
		$post_parent__in = array_map( 'absint', (array) $parent );
		if ( ! empty( $post_parent__in ) ) {
			$query_args['post_parent__in'] = $post_parent__in;
		}
	} elseif ( $parent >= 0 ) {
		$query_args['post_parent'] = $parent;
	}

	/*
	 * Maintain backward compatibility for `sort_column` key.
	 * Additionally to `WP_Query`, it has been supporting the `post_modified_gmt` field, so this logic will translate
	 * it to `post_modified` which should result in the same order given the two dates in the fields match.
	 */
	$orderby = wp_parse_list( $parsed_args['sort_column'] );
	$orderby = array_map(
		static function ( $orderby_field ) {
			$orderby_field = trim( $orderby_field );
			if ( 'post_modified_gmt' === $orderby_field || 'modified_gmt' === $orderby_field ) {
				$orderby_field = str_replace( '_gmt', '', $orderby_field );
			}
			return $orderby_field;
		},
		$orderby
	);
	if ( $orderby ) {
		$query_args['orderby'] = array_fill_keys( $orderby, $parsed_args['sort_order'] );
	}

	$order = $parsed_args['sort_order'];
	if ( $order ) {
		$query_args['order'] = $order;
	}

	if ( ! empty( $number ) ) {
		$query_args['posts_per_page'] = $number;
	}

	/**
	 * Filters query arguments passed to WP_Query in get_pages.
	 *
	 * @since 6.3.0
	 *
	 * @param array $query_args  Array of arguments passed to WP_Query.
	 * @param array $parsed_args Array of get_pages() arguments.
	 */
	$query_args = apply_filters( 'get_pages_query_args', $query_args, $parsed_args );

	$pages = new WP_Query();
	$pages = $pages->query( $query_args );

	if ( $child_of || $hierarchical ) {
		$pages = get_page_children( $child_of, $pages );
	}

	if ( ! empty( $parsed_args['exclude_tree'] ) ) {
		$exclude = wp_parse_id_list( $parsed_args['exclude_tree'] );
		foreach ( $exclude as $id ) {
			$children = get_page_children( $id, $pages );
			foreach ( $children as $child ) {
				$exclude[] = $child->ID;
			}
		}

		$num_pages = count( $pages );
		for ( $i = 0; $i < $num_pages; $i++ ) {
			if ( in_array( $pages[ $i ]->ID, $exclude, true ) ) {
				unset( $pages[ $i ] );
			}
		}
	}

	/**
	 * Filters the retrieved list of pages.
	 *
	 * @since 2.1.0
	 *
	 * @param WP_Post[] $pages       Array of page objects.
	 * @param array     $parsed_args Array of get_pages() arguments.
	 */
	return apply_filters( 'get_pages', $pages, $parsed_args );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_pages’, WP_Post[] $pages, array $parsed_args ): Filters the retrieved list of pages.
apply_filters( ‘get_pages_query_args’, array $query_args, array $parsed_args ): Filters query arguments passed to WP_Query in get_pages.

Uses	Description
wp_parse_list()`wp-includes/functions.php`	Converts a comma- or space-separated list of scalar values to an array.
get_user_by()`wp-includes/pluggable.php`	Retrieves user info by a given field.
WP_Query::__construct()`wp-includes/class-wp-query.php`	Constructor.
wp_parse_id_list()`wp-includes/functions.php`	Cleans up an array, comma- or space-separated list of IDs.
get_page_children()`wp-includes/post.php`	Identifies descendants of a given page ID in a list of page objects.
get_post_stati()`wp-includes/post.php`	Gets a list of post statuses.
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.
get_post_types()`wp-includes/post.php`	Gets a list of all registered post type objects.

Show 4 more Show less

Used by	Description
WP_Customize_Manager::has_published_pages()`wp-includes/class-wp-customize-manager.php`	Returns whether there are published pages.
WP_Posts_List_Table::_display_rows_hierarchical()`wp-admin/includes/class-wp-posts-list-table.php`
wp_dropdown_pages()`wp-includes/post-template.php`	Retrieves or displays a list of pages as a dropdown (select list).
wp_list_pages()`wp-includes/post-template.php`	Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.
get_body_class()`wp-includes/post-template.php`	Retrieves an array of the class names for the body element.

Changelog

Version	Description
6.3.0	Use WP_Query internally.
1.5.0	Introduced.

User Contributed Notes

Skip to note 4 content

Codex

11 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
Displaying pages in dropdown list
In this example a dropdown list with all the pages. Note how you can grab the link for the page with a simple call to the function get_page_link passing the ID of the page.
```
<select name="page-dropdown"
 onchange='document.location.href=this.options[this.selectedIndex].value;'> 
 <option value="">
</option> 
 ID ) . '">';
	$option .= $page->post_title;
	$option .= '</option>';
	echo $option;
  }
 ?>
</select>
```
Log in to add feedback

Skip to note 5 content

Codex

11 years ago

Displaying child pages of the current page in post format

 $post->ID, 'sort_column' => 'post_date', 'sort_order' => 'desc' ) );

foreach( $mypages as $page ) {		
	$content = $page->post_content;
	if ( ! $content ) // Check for empty page
		continue;

	$content = apply_filters( 'the_content', $content );
?>
	<h2><a href="<?php echo get_page_link( $page->ID ); ?>">post_title; ?></a></h2>
	<div class="entry"></div>

Key value pairs with page ID and Page Title This can be very useful for dropdown list

 $pages = get_pages(array('sort_column' => 'post_date', 'sort_order' => 'desc' ));  // build the key value array $selectpages = array(); foreach ($pages as $pkey => $page) { 	$selectpages[$pkey] = array( 		$page->ID => $page->post_title, 	);  }  // output  print_r($selectpages);

uri 6 years ago

Skip to note 6 content

John Sundberg

4 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

Perhaps this will save someone else some time and frustration:

Using 'any' as 'post_status', either as a string or in an array, does not work with get_pages. In fact, it completely prevents get_pages from returning any results.

Log in to add feedback

云策 WordPress 开发者社区

函数文档

get_pages()

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Hooks

Changelog

User Contributed Notes

函数文档

概述

关键要点

代码示例

注意事项

Parameters

Return

Source

Hooks

Related

Changelog

User Contributed Notes