描述:
自定义查询获取一组页面
用法:
<?php
$args = array(
'sort_order' => 'asc',
'sort_column' => 'post_title',
'hierarchical' => 1,
'exclude' => '',
'include' => '',
'meta_key' => '',
'meta_value' => '',
'authors' => '',
'child_of' => 0,
'parent' => - 1,
'exclude_tree' => '',
'number' => '',
'offset' => 0,
'post_type' => 'page',
'post_status' => 'publish'
);
$pages = get_pages($args); ?>
参数:
sort_column
(string) 以多种不同的方式对页面列表进行排序。默认设置是按页面标题的字母顺序排序。
- 'post_title' - 默认按照页面标题排序
- 'menu_order' - 按页面顺序对页面进行排序。注意页面顺序和页面ID之间的区别。页面ID是WordPress分配给每个帖子或页面的唯一编号。页面顺序可以由用户在Write>Pages管理面板中设置。
- 'post_date' - 按照发布时间
- 'post_modified' - 按最后修改的时间排序。
- 'ID' - 按照页面ID
- 'post_author' - 按照作者ID
- 'post_name' - 按后段塞按字母顺序排序。尚未支持,自WP 3.3起(请参见:http://core.trac.wordpress.org/ticket/14368)
Note: sort_column参数可用于根据WordPress数据库wp_post表中任何字段的描述符对页面列表进行排序。这里列出了一些有用的例子。
Note: get_posts()使用参数'orderby'而不是'sort_column'。另外,get_posts()会自动将post掼添加到以下值:“author,date,modified,parent,title,execpt,content”。
sort_order
(string) 更改页面列表的排序顺序(升序或降序)。默认值为升序。有效值:
- 'asc' - 从最低到最高排序(默认)。
- 'desc' - 从高到低排序。
Note: get_posts()使用参数'order'而不是'sort_order'。
exclude
(string or array) 定义要从列表中排除的页ID的逗号分隔列表(例如:“exclude=3,7,31”)。从3.0版开始,也可以使用页ID数组。没有默认值。
include
(string or array) 仅包含由get-Pages生成的列表中的某些页。与exclude类似,此参数采用以逗号分隔的页ID列表。从3.0版开始,也可以使用页ID数组。没有默认值。
Note: 如果提供此参数,则忽略child_of、parent、exclude、meta_key和meta_value参数,并将hierarchical设置为false。
child_of
(integer) 仅列出单个页的子页;将页的ID用作值。默认为0(列出所有页面)。注意,参数的child_还将获取给定ID的“孙子”,而不仅仅是直接的后代。
- 0 - 默认值, 不限制
Note: 参数的子参数不应用于页的SQL查询。它将应用于查询的结果。如果还提供了数字参数,则最终结果可能小于指定的数字。
parent
(integer) 列出将提供的单页ID作为父级的页。默认值为-1(显示所有页,而不显示父页)。请注意,“hierarchical”参数必须设置为0(false)——这不是默认值——否则除了没有父级(ID=0)和默认的所有页(ID=-1)的顶级页之外,任何页都不会返回结果。与“child-of”参数相反,此参数只返回父级的直接子级,而不返回“孙子”。通过将“child-of”参数集传递给同一(父)ID值,可以消除“hierarchical”设置为0的要求。
- -1 - 默认, 不限制父级页面
- 0 - 返回所有页面
exclude_tree
(integer) 与“child-of”相反的“exclude-tree”将从结果中移除给定ID的所有子项。用于隐藏给定页的所有子级。也可用于与“child_of”值一起隐藏孙子女。此参数在版本2.7中可用。
hierarchical
(boolean) 在其父级下列出子页或内联列出页。默认值为true(在父列表项下列出子页)。注意:此默认值将阻止元键和父页搜索查找子页。您需要设置“hierarchical”=>0,这些参数才能正常工作。有效值:
- 1 (true) - 默认值
- 0 (false)
meta_key
(string) 仅包括具有此自定义字段键的页面(与meta_value字段一起使用)。
meta_value
(string) 仅包括具有此自定义字段值的页面(与meta_key字段一起使用)。
authors
(string) 仅包括指定作者所写的页面
Note: get_posts()使用参数'author'而不是'authors'。
number
(integer) 设置要列出的页数。这将导致定义SQL限制值。默认为无限制。此参数是在版本2.8中添加的。
Note: get_posts()使用参数'numberposts'而不是'number'。
Second Note: 如果和child_of一起使用就不行了。而是使用“parent”并将“hierarchical”设置为false。
offset
(integer) 在收集一组页之前要传递(或替换)的页数。默认值为“无偏移”。此参数是在版本2.8中添加的。
post_type
("string") 显示与特定类型关联的帖子。有效值包括:
- 'post' - a post.
- 'page' - a page.
- 'revision' - a revision.
- 'attachment' - an attachment.
- Custom Post Types.
post_status
(string) 应包含的post状态类型的逗号分隔列表。例如,“publish,private,draft”。
源文件:
/**
* Retrieve a list of pages.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @since 1.5.0
*
* @param array|string $args {
* Optional. Array or string of arguments to retrieve pages.
*
* @type int $child_of Page ID to return child and grandchild pages of.
* Default 0, or no restriction.
* @type string $sort_order How to sort retrieved pages. Accepts 'ASC', 'DESC'. Default 'ASC'.
* @type string $sort_column 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'.
* @type bool $hierarchical Whether to return pages hierarchically. Default true.
* @type array $exclude Array of page IDs to exclude. Default empty array.
* @type array $include Array of page IDs to include. Cannot be used with `$child_of`,
* `$parent`, `$exclude`, `$meta_key`, `$meta_value`, or `$hierarchical`.
* Default empty array.
* @type string $meta_key Only include pages with this meta key. Default empty.
* @type string $meta_value Only include pages with this meta value. Requires `$meta_key`.
* Default empty.
* @type string $authors A comma-separated list of author IDs. Default empty.
* @type int $parent Page ID to return direct children of. `$hierarchical` must be false.
* Default -1, or no restriction.
* @type string|array $exclude_tree Comma-separated string or array of page IDs to exclude.
* Default empty array.
* @type int $number The number of pages to return. Default 0, or all pages.
* @type int $offset The number of pages to skip before returning. Requires `$number`.
* Default 0.
* @type string $post_type The post type to query. Default 'page'.
* @type string $post_status A comma-separated list of post status types to include.
* Default 'publish'.
* }
* @return array|false List of pages matching defaults or `$args`.
*/
function get_pages( $args = array() ) {
global $wpdb;
$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',
);
$r = wp_parse_args( $args, $defaults );
$number = (int) $r['number'];
$offset = (int) $r['offset'];
$child_of = (int) $r['child_of'];
$hierarchical = $r['hierarchical'];
$exclude = $r['exclude'];
$meta_key = $r['meta_key'];
$meta_value = $r['meta_value'];
$parent = $r['parent'];
$post_status = $r['post_status'];
// Make sure the post type is hierarchical.
$hierarchical_post_types = get_post_types( array( 'hierarchical' => true ) );
if ( ! in_array( $r['post_type'], $hierarchical_post_types ) ) {
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;
}
// $args can be whatever, only use the args defined in defaults to compute the key.
$key = md5( serialize( wp_array_slice_assoc( $r, array_keys( $defaults ) ) ) );
$last_changed = wp_cache_get( 'last_changed', 'posts' );
if ( ! $last_changed ) {
$last_changed = microtime();
wp_cache_set( 'last_changed', $last_changed, 'posts' );
}
$cache_key = "get_pages:$key:$last_changed";
if ( $cache = wp_cache_get( $cache_key, 'posts' ) ) {
// Convert to WP_Post instances.
$pages = array_map( 'get_post', $cache );
/** This filter is documented in wp-includes/post.php */
$pages = apply_filters( 'get_pages', $pages, $r );
return $pages;
}
$inclusions = '';
if ( ! empty( $r['include'] ) ) {
$child_of = 0; //ignore child_of, parent, exclude, meta_key, and meta_value params if using include
$parent = -1;
$exclude = '';
$meta_key = '';
$meta_value = '';
$hierarchical = false;
$incpages = wp_parse_id_list( $r['include'] );
if ( ! empty( $incpages ) ) {
$inclusions = ' AND ID IN (' . implode( ',', $incpages ) . ')';
}
}
$exclusions = '';
if ( ! empty( $exclude ) ) {
$expages = wp_parse_id_list( $exclude );
if ( ! empty( $expages ) ) {
$exclusions = ' AND ID NOT IN (' . implode( ',', $expages ) . ')';
}
}
$author_query = '';
if ( ! empty( $r['authors'] ) ) {
$post_authors = preg_split( '/[s,]+/', $r['authors'] );
if ( ! empty( $post_authors ) ) {
foreach ( $post_authors as $post_author ) {
//Do we have an author id or an author login?
if ( 0 == intval($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;
}
if ( '' == $author_query ) {
$author_query = $wpdb->prepare(' post_author = %d ', $post_author);
} else {
$author_query .= $wpdb->prepare(' OR post_author = %d ', $post_author);
}
}
if ( '' != $author_query ) {
$author_query = " AND ($author_query)";
}
}
}
$join = '';
$where = "$exclusions $inclusions ";
if ( '' !== $meta_key || '' !== $meta_value ) {
$join = " LEFT JOIN $wpdb->postmeta ON ( $wpdb->posts.ID = $wpdb->postmeta.post_id )";
// meta_key and meta_value might be slashed
$meta_key = wp_unslash($meta_key);
$meta_value = wp_unslash($meta_value);
if ( '' !== $meta_key ) {
$where .= $wpdb->prepare(" AND $wpdb->postmeta.meta_key = %s", $meta_key);
}
if ( '' !== $meta_value ) {
$where .= $wpdb->prepare(" AND $wpdb->postmeta.meta_value = %s", $meta_value);
}
}
if ( is_array( $parent ) ) {
$post_parent__in = implode( ',', array_map( 'absint', (array) $parent ) );
if ( ! empty( $post_parent__in ) ) {
$where .= " AND post_parent IN ($post_parent__in)";
}
} elseif ( $parent >= 0 ) {
$where .= $wpdb->prepare(' AND post_parent = %d ', $parent);
}
if ( 1 == count( $post_status ) ) {
$where_post_type = $wpdb->prepare( "post_type = %s AND post_status = %s", $r['post_type'], reset( $post_status ) );
} else {
$post_status = implode( "', '", $post_status );
$where_post_type = $wpdb->prepare( "post_type = %s AND post_status IN ('$post_status')", $r['post_type'] );
}
$orderby_array = array();
$allowed_keys = array( 'author', 'post_author', 'date', 'post_date', 'title', 'post_title', 'name', 'post_name', 'modified',
'post_modified', 'modified_gmt', 'post_modified_gmt', 'menu_order', 'parent', 'post_parent',
'ID', 'rand', 'comment_count' );
foreach ( explode( ',', $r['sort_column'] ) as $orderby ) {
$orderby = trim( $orderby );
if ( ! in_array( $orderby, $allowed_keys ) ) {
continue;
}
switch ( $orderby ) {
case 'menu_order':
break;
case 'ID':
$orderby = "$wpdb->posts.ID";
break;
case 'rand':
$orderby = 'RAND()';
break;
case 'comment_count':
$orderby = "$wpdb->posts.comment_count";
break;
default:
if ( 0 === strpos( $orderby, 'post_' ) ) {
$orderby = "$wpdb->posts." . $orderby;
} else {
$orderby = "$wpdb->posts.post_" . $orderby;
}
}
$orderby_array[] = $orderby;
}
$sort_column = ! empty( $orderby_array ) ? implode( ',', $orderby_array ) : "$wpdb->posts.post_title";
$sort_order = strtoupper( $r['sort_order'] );
if ( '' !== $sort_order && ! in_array( $sort_order, array( 'ASC', 'DESC' ) ) ) {
$sort_order = 'ASC';
}
$query = "SELECT * FROM $wpdb->posts $join WHERE ($where_post_type) $where ";
$query .= $author_query;
$query .= " ORDER BY " . $sort_column . " " . $sort_order ;
if ( ! empty( $number ) ) {
$query .= ' LIMIT ' . $offset . ',' . $number;
}
$pages = $wpdb->get_results($query);
if ( empty($pages) ) {
/** This filter is documented in wp-includes/post.php */
$pages = apply_filters( 'get_pages', array(), $r );
return $pages;
}
// Sanitize before caching so it'll only get done once.
$num_pages = count($pages);
for ($i = 0; $i < $num_pages;="" $i++)="" {="" $pages[$i]="sanitize_post($pages[$i]," 'raw');="" }="" update="" cache.="" update_post_cache(="" $pages="" );="" if="" (="" $child_of="" ||="" $hierarchical="" )="" {="" $pages="get_page_children($child_of," $pages);="" }="" if="" (="" !="" empty(="" $r['exclude_tree']="" )="" )="" {="" $exclude="wp_parse_id_list(" $r['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 ) ) {
unset( $pages[$i] );
}
}
}
$page_structure = array();
foreach ( $pages as $page ) {
$page_structure[] = $page->ID;
}
wp_cache_set( $cache_key, $page_structure, 'posts' );
// Convert to WP_Post instances
$pages = array_map( 'get_post', $pages );
/**
* Filter the retrieved list of pages.
*
* @since 2.1.0
*
* @param array $pages List of pages to retrieve.
* @param array $r Array of get_pages() arguments.
*/
return apply_filters( 'get_pages', $pages, $r );
}
//
// Attachment functions
//