云策 WordPress 开发者社区

函数文档

get_post_ancestors()

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

概述

get_post_ancestors() 函数用于获取文章或页面的祖先ID数组，适用于处理层级结构如页面树。它接受文章ID或WP_Post对象作为参数，返回祖先ID数组或空数组。

关键要点

  • 参数：$post（必需），可以是整数ID或WP_Post对象。
  • 返回值：整数数组，包含祖先ID，若无祖先则返回空数组。
  • 函数内部通过循环检测避免无限循环，确保数据完整性。
  • 自WordPress 2.5.0版本引入，是处理文章层级关系的核心函数。

代码示例

// 获取当前页面的祖先ID数组
$ancestors = get_post_ancestors( get_the_ID() );

// 示例：获取顶级页面缩略图
$parents = get_post_ancestors( $post->ID );
if ( ! empty( $parents ) ) {
    $id = array_pop( $parents );
}
if ( has_post_thumbnail( $id ) ) {
    echo get_the_post_thumbnail( $id, 'thumbnail' );
}

注意事项

  • 祖先ID数组按从直接父级到顶级祖先的顺序排列，例如[直接父ID, 上一级ID, ... 顶级ID]。
  • 函数依赖get_post()获取文章数据，确保参数有效以避免错误。
  • 在循环中使用时，注意性能影响，特别是深层嵌套结构。
📄 原文内容

Retrieves the IDs of the ancestors of a post.

Parameters

$postint|WP_Postrequired
Post ID or post object.

Return

int[] Array of ancestor IDs or empty array if there are none.

Source

function get_post_ancestors( $post ) {
	$post = get_post( $post );

	if ( ! $post || empty( $post->post_parent ) || $post->post_parent === $post->ID ) {
		return array();
	}

	$ancestors = array();

	$id          = $post->post_parent;
	$ancestors[] = $id;

	while ( $ancestor = get_post( $id ) ) {
		// Loop detection: If the ancestor has been seen before, break.
		if ( empty( $ancestor->post_parent ) || $ancestor->post_parent === $post->ID
			|| in_array( $ancestor->post_parent, $ancestors, true )
		) {
			break;
		}

		$id          = $ancestor->post_parent;
		$ancestors[] = $id;
	}

	return $ancestors;
}

View all references View on Trac View on GitHub

Uses Description
get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.
Used by Description
WP_Posts_List_Table::single_row()wp-admin/includes/class-wp-posts-list-table.php
get_ancestors()wp-includes/taxonomy.php

Gets an array of ancestor IDs for a given object.
WP_Post::__get()wp-includes/class-wp-post.php

Getter.

Changelog

Version Description
2.5.0 Introduced.

User Contributed Notes

  2. Skip to note 6 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Get Ancestors Page Slug
    This example returns the highest page {slug} in a tree and uses it as a Body_Class, so the parent and all children will have the same Body Class!

    This example for a twenty eleven child theme in the header.php file

    </head>

ID );
	/* Get the top Level page->ID count base 1, array base 0 so -1 */ 
	$id = ($parents) ? $parents[count($parents)-1]: $post->ID;
	/* Get the parent and set the $class with the page slug (post_name) */
	$parent = get_post( $id );
	$class = $parent->post_name;
}
?>

<body <?php body_class( $class ); ?>>

  3. Skip to note 7 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Get Ancestors Post Meta
    If we did not want to use the page slug, we could use a custom field eg: body_class, on the top level page and set the class in the post meta.

    </head>

ID );
	$id = ($parents) ? $parents[count($parents)-1]: $post->ID;
	$class = get_post_meta( $id, 'body_class', true );
}
?>

<body <?php body_class( $class ); ?>>

  4. Skip to note 8 content


    Brandon Zhang


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Suppose we have this pages structure:

    • Top level page (ID: 107)
      • 2nd level page (ID: 997)
        • 3rd level page (ID: 1090)
          • Current post

    [0] => int(1090) [1] => int(997) [2] => int(107)

    So, if you want to get its direct parent page, then use the first element, or use the last element if you want to get the top level page.