云策 WordPress 开发者社区

函数文档

get_boundary_post()

查看官方原文 ↗
💡 云策文档标注

概述

get_boundary_post() 函数用于检索边界文章，即根据发布日期在指定约束条件下的第一或最后一篇文章。它支持通过分类法术语和排除项进行筛选，返回文章对象数组或 null。

关键要点

  • 边界文章定义为在 $in_same_term 或 $excluded_terms 约束下，按发布日期排序的第一篇或最后一篇文章。
  • 参数包括 $in_same_term（布尔值，是否在同一分类法术语中）、$excluded_terms（数组或逗号分隔的排除术语ID）、$start（布尔值，是否检索第一篇，默认为 true）和 $taxonomy（字符串，分类法名称，默认为 'category'）。
  • 返回值是包含边界文章对象的数组（成功时）或 null（失败时）。
  • 函数内部使用 WP_Query 参数构建查询，并处理分类法相关逻辑。
  • 注意事项：函数在非单篇文章页面、附件页面或分类法不存在时返回 null。

代码示例

// 获取当前文章在同一分类法术语中的第一篇边界文章
$boundary_post = get_boundary_post(true, '', true, 'category');
if ($boundary_post) {
    echo $boundary_post[0]->post_title;
}

// 获取排除特定术语ID的最后一篇边界文章
$excluded_terms = '1,2,3';
$boundary_post = get_boundary_post(false, $excluded_terms, false, 'post_tag');
if ($boundary_post) {
    echo $boundary_post[0]->post_title;
}

注意事项

  • 函数自 WordPress 2.8.0 版本引入，但用户反馈在 WordPress 6+ 中可能存在问题，需测试兼容性。
  • 相关函数包括 get_boundary_post_rel_link()（已弃用）、is_single()、is_attachment()、wp_get_object_terms() 等。
  • 使用时需确保当前环境为单篇文章页面，且分类法存在。
📄 原文内容

Retrieves the boundary post.

Description

Boundary being either the first or last post by publish date within the constraints specified by $in_same_term or $excluded_terms.

Parameters

$in_same_termbooloptional
Whether returned post should be in the same taxonomy term.

Default:false

$excluded_termsint[]|stringoptional
Array or comma-separated list of excluded term IDs.
Default empty.
$startbooloptional
Whether to retrieve first or last post.

Default:true

$taxonomystringoptional
Taxonomy, if $in_same_term is true. Default 'category'.

Return

array|null Array containing the boundary post object if successful, null otherwise.

More Information

get_boundary_post() will set the post pointer to the first post.

Source

function get_boundary_post( $in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category' ) {
	$post = get_post();

	if ( ! $post || ! is_single() || is_attachment() || ! taxonomy_exists( $taxonomy ) ) {
		return null;
	}

	$query_args = array(
		'posts_per_page'         => 1,
		'order'                  => $start ? 'ASC' : 'DESC',
		'update_post_term_cache' => false,
		'update_post_meta_cache' => false,
	);

	$term_array = array();

	if ( ! is_array( $excluded_terms ) ) {
		if ( ! empty( $excluded_terms ) ) {
			$excluded_terms = explode( ',', $excluded_terms );
		} else {
			$excluded_terms = array();
		}
	}

	if ( $in_same_term || ! empty( $excluded_terms ) ) {
		if ( $in_same_term ) {
			$term_array = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) );
		}

		if ( ! empty( $excluded_terms ) ) {
			$excluded_terms = array_map( 'intval', $excluded_terms );
			$excluded_terms = array_diff( $excluded_terms, $term_array );

			$inverse_terms = array();
			foreach ( $excluded_terms as $excluded_term ) {
				$inverse_terms[] = $excluded_term * -1;
			}
			$excluded_terms = $inverse_terms;
		}

		$query_args['tax_query'] = array(
			array(
				'taxonomy' => $taxonomy,
				'terms'    => array_merge( $term_array, $excluded_terms ),
			),
		);
	}

	return get_posts( $query_args );
}

View all references View on Trac View on GitHub

Uses Description
is_single()wp-includes/query.php

Determines whether the query is for an existing single post.
is_attachment()wp-includes/query.php

Determines whether the query is for an existing attachment page.
wp_get_object_terms()wp-includes/taxonomy.php

Retrieves the terms associated with the given object(s), in the supplied taxonomies.
taxonomy_exists()wp-includes/taxonomy.php

Determines whether the taxonomy name exists.
get_posts()wp-includes/post.php

Retrieves an array of the latest posts, or posts matching the given criteria.
get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.

Show 1 moreShow less

Used by Description
get_boundary_post_rel_link()wp-includes/deprecated.php

Get boundary post relational link.

Changelog

Version Description
2.8.0 Introduced.

User Contributed Notes