当前浏览:首页 / WordPress函数 / get_posts()

get_posts( array $args = null )

检索最新文章的数组,或与给定条件匹配的文章

postsmore...


描述

有关可用参数的更多信息,请参阅开发人员手册中的WP_Query文档。

此函数忽略$ignore_sticky_posts$no_found_rows参数,并将两者设置为true

默认值如下:

另见

  • WP_Query
  • WP_Query::parse_query()

参数

$args

(array) (可选) 检索文章的参数。有关所有可用参数,请参见WP_Query::parse_query()

  • 'numberposts'
    (int) 要检索的文章总数,是在 WP_Query 中的 $posts_per_page 参数的别称,接受 -1 (全部)默认 5
  • 'category'
    (int|string) 类别ID或以逗号分隔的ID列表 (此类别或任何子类),是在 WP_Query 中的 $cat 参数的别称,默认 0
  • 'include'
    (int[]) 要检索的文章ID数组,置顶文章将被包括在内。是在 WP_Query 中的 $post__in 参数的别称,默认是空数组
  • 'exclude'
    (int[]) 要排除的文章ID数组,默认为空数组
  • 'suppress_filters'
    (bool) 是否抑制过滤器,默认为true

默认值: null


返回

(WP_Post[]|int[]) 文章对象或文章 ID的数组。


说明

get_posts 最合适的用法是基于一组参数创建文章数组。它检索最近发布或与此条件匹配的发布的列表。get_posts 也可以用于创建多个循环,不过在这种情况下,最好使用新的WP_Query更直接地引用WP_Query。

get_posts 的参数与 get_pages 的参数类似,但实现方式不同,应在适当的场景中使用。get_posts 使用WP_Query,而 get_pages 更直接地查询数据库。每个参数都反映了实现中的这种差异。

query_posts 也使用WP_Query,但不推荐使用,因为它通过更改全局变量 $wp_query 直接改变主循环。另一方面,get_posts 只引用一个新的WP_Query对象,因此不会影响或改变主循环。

如果您想在执行前更改主查询,可以使用 pre_get_posts 钩子。如果您只想基于页面中的一组小而简单的参数调用文章数组,那么 get_posts 是您的最佳选择。



源码

查看源码 官方文档


更新日志

版本描述
1.2.0开始引入

用户贡献的笔记

  • 贡献者:Aurovrata Venet

    返回具有属性的WP_Post对象数组,

    WP_Post Object
    (
        [ID] =>
        [post_author] =>
        [post_date] => 
        [post_date_gmt] => 
        [post_content] => 
        [post_title] => 
        [post_excerpt] => 
        [post_status] =>
        [comment_status] =>
        [ping_status] => 
        [post_password] => 
        [post_name] =>
        [to_ping] => 
        [pinged] => 
        [post_modified] => 
        [post_modified_gmt] =>
        [post_content_filtered] => 
        [post_parent] => 
        [guid] => 
        [menu_order] =>
        [post_type] =>
        [post_mime_type] => 
        [comment_count] =>
        [filter] =>
    )
    
  • 贡献者:Nico

    获取博客中最近10篇文章的示例:

    $args = array(
      'numberposts' => 10
    );
    
    $latest_posts = get_posts( $args );
    

    如果要从自定义文章类型获取文章,也可以传递post_type参数,例如:

    $args = array(
      'numberposts' => 10,
      'post_type'   => 'book'
    );
    
    $latest_books = get_posts( $args );
    
  • 贡献者:swedish boy

    文章ID数组

    要返回ID而不是post对象,请使用fields参数。

    $args = array('fields' => 'ids');
    $posts = get_posts($args);
    // if any posts are found $posts will be an array with their ids
    

    fields参数可以设置为'ids''all'默认值)或'id=>parent'。最后两个(参数)将返回stdClass对象的数组。

  • 贡献者:Codex

    自定义字段参数

    显示与某个自定义字段关联的文章。下面的示例使用“meta_query”显示来自“product”文章类型的文章,其中meta key为“featured”,值为“yes”:

    $args = array(
    	'post_type'  => 'product',
    	'meta_query' => array(
    		array(
    			'key'   => 'featured',
    			'value' => 'yes',
    		)
    	)
    );
    $postslist = get_posts( $args );
    

    有关更多示例,请参阅WP_Query文档的“自定义字段参数”部分。

  • 贡献者:Codex

    发布上一个下一个导航

    您还可以使用自定义查询在上一篇文章和下一篇文章导航中创建文章。以下是使其可行的方法。

    <?php
    $post_list = get_posts( array(
    	'orderby'    => 'menu_order',
    	'sort_order' => 'asc'
    ) );
    
    $posts = array();
    
    foreach ( $post_list as $post ) {
       $posts[] += $post->ID;
    }
    
    $current = array_search( get_the_ID(), $posts );
    
    $prevID = $posts[ $current-1 ];
    $nextID = $posts[ $current+1 ];
    ?>
    
    <div class="navigation">
    <?php if ( ! empty( $prevID ) ): ?>
    	<div class="alignleft">
    		<a href="<?php echo get_permalink( $prevID ); ?>" alt="<?php echo get_the_title( $prevID ); ?>">
    			<?php _e( 'Previous', 'textdomain' ); ?>
    		</a>
    	</div>
    <?php endif;
    
    if ( ! empty( $nextID ) ) : ?>
    	<div class="alignright">
    		<a href="<?php echo get_permalink( $nextID ); ?>" alt="<?php echo get_the_title( $nextID ); ?>">
    			<?php _e( 'Next', 'textdomain' ); ?>
    		</a>
    	</div>
    <?php endif; ?>
    </div><!-- .navigation -->
    

    使用偏移量重置后发列表

    如果在循环之后需要加入foreach之前的帖子,可以使用以下内容:

    <?php
    $post_list = get_posts( array(
    	'orderby'    => 'menu_order',
    	'sort_order' => 'asc'
    ) );
    
    $posts = array();
    
    foreach ( $post_list as $post ) {
       $posts[] += $post->ID;
    }
    
    $current = array_search( get_the_ID(), $posts );
    
    $prevID = $posts[ $current-1 ];
    $nextID = $posts[ $current+1 ];
    ?>
    
    <div class="navigation">
    <?php if ( ! empty( $prevID ) ): ?>
    	<div class="alignleft">
    		<a href="<?php echo get_permalink( $prevID ); ?>" alt="<?php echo get_the_title( $prevID ); ?>">
    			<?php _e( 'Previous', 'textdomain' ); ?>
    		</a>
    	</div>
    <?php endif;
    
    if ( ! empty( $nextID ) ) : ?>
    	<div class="alignright">
    		<a href="<?php echo get_permalink( $nextID ); ?>" alt="<?php echo get_the_title( $nextID ); ?>">
    			<?php _e( 'Next', 'textdomain' ); ?>
    		</a>
    	</div>
    <?php endif; ?>
    </div><!-- .navigation -->
    
  • 贡献者:Codex

    访问所有post数据

    默认情况下,某些post相关数据不可用于get_posts,例如通过 the_content() 或数字ID获取的post内容。这可以通过调用内部函数 setup_postdata() 来解决,该函数的参数为$post数组:

    <?php
    $lastposts = get_posts( array(
    	'posts_per_page' => 3
    ) );
    
    if ( $lastposts ) {
    	foreach ( $lastposts as $post ) :
    		setup_postdata( $post ); ?>
    		<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
    		<?php the_content(); ?>
    	<?php
    	endforeach; 
    	wp_reset_postdata();
    }
    

    要访问文章的ID或内容而不调用setup_postdata(),或者实际上是任何文章特定的数据(保留在文章表中的数据),可以使用$post->COLUMN,其中COLUMN是数据的表列名。所以 $post->ID 保存ID,$post->post_content 保存内容等等。要在页面上显示或打印这些数据,请使用PHP echo命令,如下所示:

    <?php echo $post->ID; ?>
    
  • 贡献者:Codex

    分类参数

    显示与某些分类相关的文章。如果指定注册到自定义文章类型的分类法,则不使用“category”,而是使用 ‘{custom_taxonomy_name}’。例如,如果您有一个名为“genre”的自定义分类法,并且只想显示来自“genre”中“jazz”的文章,那么您将使用以下代码。

    $show_albums = get_posts( array(
    	 'posts_per_page' => 8,
    	 'orderby'        => 'rand',
    	 'post_type'      => 'albums',
    	 'genre'          => 'jazz',
    	 'post_status'    => 'publish'
    ) );
    

    以下示例使用“tax_query”在“genre”自定义分类下显示标记为“jazz”的文章:

    $args = array(
    	'tax_query' => array(
    		array(
    			'taxonomy' => 'genre',
    			'field'    => 'slug',
    			'terms'    => 'jazz'
    		)
    	)
    );
    $postslist = get_posts( $args );
    

    有关更多示例,请参阅WP_Query文档的分类参数部分。

  • 贡献者:Jules Colle

    获取任何文章类型的所有已发布文章:

    $posts = get_posts( array(
      'post_type' => get_post_types(),
      'post_status' => 'publish',
      'numberposts' => -1,
    ) );
  • 贡献者:Codex

    通过它的slug获取文章

    允许您通过post slug获取post ID。

    <?php
    $the_slug = 'my-slug';
    $args=array(
    	'name'           => $the_slug,
    	'post_type'      => 'post',
    	'post_status'    => 'publish',
    	'posts_per_page' => 1
    );
    $my_posts = get_posts( $args );
    
    if ( $my_posts ) {
    	printf( __( 'ID on the first post found %s', 'textdomain' ), esc_html( $my_posts[0]->ID ) );
    }
    
  • 贡献者:Toao.net

    orderby也接受值post__in。(注意post和in之间有两个下划线。)如果您使用include检索特定文章,文章将按照您提供的包含顺序提供。例如:

    $posts = get_posts( array(
    	'include'   => '3,8,1,17',
    	'post_type' => 'attachment',
    	'orderby'   => 'post__in',
    ) );
    
  • 贡献者:Codex

    显示所有附件

    在模板中的任何循环之外执行此操作。

    <?php
    $attachments = get_posts( array(
    	'post_type'      => 'attachment',
    	'posts_per_page' => 500,
    	'post_status'    => 'any',
    	'post_parent'    => null
    ) );
    
    if ( $attachments ) {
    	foreach ( $attachments as $post ) {
    		setup_postdata( $post );
    		the_title();
    		the_attachment_link( $post->ID, false );
    		the_excerpt();
    	}
    	wp_reset_postdata();
    }
    ?>
    
  • 贡献者:jonburnaby

    如果根据指定和默认参数值未找到帖子,则不视为错误情况。相反,函数返回一个空数组(“array()”)。

  • 贡献者:Rolf Allard van Hagen

    显示文章或文章类型“album”的示例,在“genre”自定义分类下标记为“jazz”或“improv”:

    $args = array(
        'post_type' => 'album',
        'post_status' => 'publish',
        'tax_query' => array(
            array(
                'taxonomy' => 'genre',
                'field'    => 'slug',
                'terms'    => array( 'jazz', 'improv' )
            )
        )
    );
    $postslist = get_posts( $args );
    

    注意,简单的'{custom_taxonomy_name}' => 'jazz'已被弃用,取而代之的是tax_query。更复杂的例子可以在WP_Query文档上找到

  • 贡献者:Codex

    按标题排序的最新帖子

    为了显示按字母顺序升序排列的最后十篇文章,下面将显示其发布日期、标题和摘录:

    $postslist = get_posts( array(
    	'posts_per_page' => 10,
    	'order'          => 'ASC',
    	'orderby'        => 'title'
    ) );
    
    if ( $postslist ) {
    	foreach ( $postslist as $post ) :
    		setup_postdata( $post );
    		?>
    		<div>
    			<?php the_date(); ?>
    			<br />
    			<?php the_title(); ?>   
    			<?php the_excerpt(); ?>
    		</div>
    	<?php
    	endforeach; 
    	wp_reset_postdata();
    }
    
  • 贡献者:Codex

    随机文章

    使用MySQL RAND() 函数为orderby参数值显示随机选择的5篇文章的列表:

    <ul>
    	<?php
    	$rand_posts = get_posts( array(
    		'posts_per_page' => 5,
    		'orderby'        => 'rand'
    	) );
    	
    	if ( $rand_posts ) {
    	foreach ( $rand_posts as $post ) : 
    		setup_postdata( $post );
    		?>
    		<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
    		<?php
    	endforeach; 
    	wp_reset_postdata();
    	}
    	?>
    </ul>
    
  • 贡献者:Codex

    显示当前文章的附件

    在循环内执行此操作(其中 $post->ID 可用)

    $attachments = get_posts( array(
    	'post_type'      => 'attachment',
    	'posts_per_page' => -1,
    	'post_status'    => 'any',
    	'post_parent'    => $post->ID
    ) );
    
    if ( $attachments ) {
    	foreach ( $attachments as $attachment ) {
    		echo apply_filters( 'the_title' , $attachment->post_title );
    		the_attachment_link( $attachment->ID , false );
    	}
    }
    
  • 贡献者:u22

    按文章类型名称排序结果

    如果您有一个自定义post类型的数组,您还可以按post_type名称对结果排序,如果您需要对结果进行“分组”,则此操作有效。

    <?php
    		$args = array(
    			'posts_per_page' => 10,
    			'post_type'      => array('page','post'),
    			'post_status'    => 'publish',
    			'offset'	 => 0,
    			's'    		 => 'Lorem',
    			'orderby'        => 'post_type',
            		'order'          => 'ASC'
    		);
    		 $posts = get_posts( $args );
    ?>
    
  • 贡献者:Amy

    按标题查找文章

    要按标题查找文章,数组键为“title”,而不是“post_title”:

    $post_array = get_posts( array(
      'post_status' => 'publish',
      'title' => 'my_post_title',
    ) );
    
  • 贡献者:Codex

    带有偏移的文章列表

    如果您的博客配置为在头版上仅显示一篇文章,但还希望在类别ID 1中列出指向前五篇文章的链接,则可以使用此选项:

    <ul>
    	<?php
    	$myposts = get_posts( $array(
    		'posts_per_page' => 5,
    		'offset'         => 1,
    		'category'       => 1
    	) );
    
    	if ( $myposts ) {
    		foreach ( $myposts as $post ) :
    			setup_postdata( $post );
    			?>
    			<li>
    				<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
    			</li>
    		<?php
    		endforeach; 
    		wp_reset_postdata();
    	}
    	?>
    </ul>
    

    注意:使用偏移量时,上述查询应仅用于其中包含多个文章的类别,否则将没有输出。