WordPress开发手册:get_posts()

函数原型

get_posts( array $args = null ): WP_Post[]|int[]

函数描述

是否弃用

未弃用

函数参数

$args
array
Optional

Arguments to retrieve posts. See WP_Query::parse_query() for all available arguments.

• numberposts int
  Total number of posts to retrieve. Is an alias of $posts_per_page in WP_Query. Accepts -1 for all. Default 5.
• category int|string
  Category ID or comma-separated list of IDs (this or any children).
  Is an alias of $cat in WP_Query. Default 0.
• include int[]
  An array of post IDs to retrieve, sticky posts will be included.
  Is an alias of $post__in in WP_Query. Default empty array.
• exclude int[]
  An array of post IDs not to retrieve. Default empty array.
• suppress_filters bool
  Whether to suppress filters. Default true.

More Arguments from WP_Query::parse_query( … $query )

Array or string of Query parameters.

• attachment_id int
  Attachment post ID. Used for 'attachment' post_type.
• author int|string
  Author ID, or comma-separated list of IDs.
• author_name string
  User 'user_nicename'.
• author__in int[]
  An array of author IDs to query from.
• author__not_in int[]
  An array of author IDs not to query from.
• cache_results bool
  Whether to cache post information. Default true.
• cat int|string
  Category ID or comma-separated list of IDs (this or any children).
• category__and int[]
  An array of category IDs (AND in).
• category__in int[]
  An array of category IDs (OR in, no children).
• category__not_in int[]
  An array of category IDs (NOT in).
• category_name string
  Use category slug (not name, this or any children).
• comment_count array|int
  Filter results by comment count. Provide an integer to match comment count exactly. Provide an array with integer 'value' and 'compare' operator ('=', '!=', '>', '>=', '<', '<=' ) to compare against comment_count in a specific way.
• comment_status string
  Comment status.
• comments_per_page int
  The number of comments to return per page.
  Default 'comments_per_page' option.
• date_query array
  An associative array of WP_Date_Query arguments.
  See WP_Date_Query::__construct().
• day int
  Day of the month. Accepts numbers 1-31.
• exact bool
  Whether to search by exact keyword. Default false.
• fields string
  Post fields to query for. Accepts:

  • '' Returns an array of complete post objects (WP_Post[]).
  • 'ids' Returns an array of post IDs (int[]).
  • 'id=>parent' Returns an associative array of parent post IDs, keyed by post ID (int[]).

  Default ''.

• hour int
  Hour of the day. Accepts numbers 0-23.
• ignore_sticky_posts int|bool
  Whether to ignore sticky posts or not. Setting this to false excludes stickies from 'post__in'. Accepts 1|true, 0|false.
  Default false.
• m int
  Combination YearMonth. Accepts any four-digit year and month numbers 01-12.
• meta_key string|string[]
  Meta key or keys to filter by.
• meta_value string|string[]
  Meta value or values to filter by.
• meta_compare string
  MySQL operator used for comparing the meta value.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_compare_key string
  MySQL operator used for comparing the meta key.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_type string
  MySQL data type that the meta_value column will be CAST to for comparisons.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_type_key string
  MySQL data type that the meta_key column will be CAST to for comparisons.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_query array
  An associative array of WP_Meta_Query arguments.
  See WP_Meta_Query::__construct() for accepted values.
• menu_order int
  The menu order of the posts.
• minute int
  Minute of the hour. Accepts numbers 0-59.
• monthnum int
  The two-digit month. Accepts numbers 1-12.
• name string
  Post slug.
• nopaging bool
  Show all posts (true) or paginate (false). Default false.
• no_found_rows bool
  Whether to skip counting the total rows found. Enabling can improve performance. Default false.
• offset int
  The number of posts to offset before retrieval.
• order string
  Designates ascending or descending order of posts. Default 'DESC'.
  Accepts 'ASC', 'DESC'.
• orderby string|array
  Sort retrieved posts by parameter. One or more options may be passed.
  To use 'meta_value', or 'meta_value_num', 'meta_key=keyname' must be also be defined. To sort by a specific $meta_query clause, use that clause’s array key. Accepts:

  • 'none'
  • 'name'
  • 'author'
  • 'date'
  • 'title'
  • 'modified'
  • 'menu_order'
  • 'parent'
  • 'ID'
  • 'rand'
  • 'relevance'
  • 'RAND(x)' (where 'x' is an integer seed value)
  • 'comment_count'
  • 'meta_value'
  • 'meta_value_num'
  • 'post__in'
  • 'post_name__in'
  • 'post_parent__in'
  • The array keys of $meta_query.

  Default is 'date', except when a search is being performed, when the default is 'relevance'.

• p int
  Post ID.
• page int
  Show the number of posts that would show up on page X of a static front page.
• paged int
  The number of the current page.
• page_id int
  Page ID.
• pagename string
  Page slug.
• perm string
  Show posts if user has the appropriate capability.
• ping_status string
  Ping status.
• post__in int[]
  An array of post IDs to retrieve, sticky posts will be included.
• post__not_in int[]
  An array of post IDs not to retrieve. Note: a string of comma- separated IDs will NOT work.
• post_mime_type string
  The mime type of the post. Used for 'attachment' post_type.
• post_name__in string[]
  An array of post slugs that results must match.
• post_parent int
  Page ID to retrieve child pages for. Use 0 to only retrieve top-level pages.
• post_parent__in int[]
  An array containing parent page IDs to query child pages from.
• post_parent__not_in int[]
  An array containing parent page IDs not to query child pages from.
• post_type string|string[]
  A post type slug (string) or array of post type slugs.
  Default 'any' if using 'tax_query'.
• post_status string|string[]
  A post status (string) or array of post statuses.
• posts_per_page int
  The number of posts to query for. Use -1 to request all posts.
• posts_per_archive_page int
  The number of posts to query for by archive page. Overrides 'posts_per_page' when is_archive() , or is_search() are true.
• s string
  Search keyword(s). Prepending a term with a hyphen will exclude posts matching that term. Eg, ‘pillow -sofa’ will return posts containing 'pillow' but not 'sofa'. The character used for exclusion can be modified using the the 'wp_query_search_exclusion_prefix' filter.
• second int
  Second of the minute. Accepts numbers 0-59.
• sentence bool
  Whether to search by phrase. Default false.
• suppress_filters bool
  Whether to suppress filters. Default false.
• tag string
  Tag slug. Comma-separated (either), Plus-separated (all).
• tag__and int[]
  An array of tag IDs (AND in).
• tag__in int[]
  An array of tag IDs (OR in).
• tag__not_in int[]
  An array of tag IDs (NOT in).
• tag_id int
  Tag id or comma-separated list of IDs.
• tag_slug__and string[]
  An array of tag slugs (AND in).
• tag_slug__in string[]
  An array of tag slugs (OR in). unless 'ignore_sticky_posts' is true. Note: a string of comma-separated IDs will NOT work.
• tax_query array
  An associative array of WP_Tax_Query arguments.
  See WP_Tax_Query::__construct().
• title string
  Post title.
• update_post_meta_cache bool
  Whether to update the post meta cache. Default true.
• update_post_term_cache bool
  Whether to update the post term cache. Default true.
• update_menu_item_cache bool
  Whether to update the menu item cache. Default false.
• lazy_load_term_meta bool
  Whether to lazy-load term meta. Setting to false will disable cache priming for term meta, so that each get_term_meta() call will hit the database.
  Defaults to the value of $update_post_term_cache.
• w int
  The week number of the year. Accepts numbers 0-53.
• year int
  The four-digit year. Accepts any four-digit year.

Default: null

函数返回值

函数位置

函数源码

function get_posts( $args = null ) {
	$defaults = array(
		'numberposts'      => 5,
		'category'         => 0,
		'orderby'          => 'date',
		'order'            => 'DESC',
		'include'          => array(),
		'exclude'          => array(),
		'meta_key'         => '',
		'meta_value'       => '',
		'post_type'        => 'post',
		'suppress_filters' => true,
	);

	$parsed_args = wp_parse_args( $args, $defaults );
	if ( empty( $parsed_args['post_status'] ) ) {
		$parsed_args['post_status'] = ( 'attachment' === $parsed_args['post_type'] ) ? 'inherit' : 'publish';
	}
	if ( ! empty( $parsed_args['numberposts'] ) && empty( $parsed_args['posts_per_page'] ) ) {
		$parsed_args['posts_per_page'] = $parsed_args['numberposts'];
	}
	if ( ! empty( $parsed_args['category'] ) ) {
		$parsed_args['cat'] = $parsed_args['category'];
	}
	if ( ! empty( $parsed_args['include'] ) ) {
		$incposts                      = wp_parse_id_list( $parsed_args['include'] );
		$parsed_args['posts_per_page'] = count( $incposts );  // Only the number of posts included.
		$parsed_args['post__in']       = $incposts;
	} elseif ( ! empty( $parsed_args['exclude'] ) ) {
		$parsed_args['post__not_in'] = wp_parse_id_list( $parsed_args['exclude'] );
	}

	$parsed_args['ignore_sticky_posts'] = true;
	$parsed_args['no_found_rows']       = true;

	$get_posts = new WP_Query;
	return $get_posts->query( $parsed_args );

}

源码链接

WordPress
Github

变更日志