云策 WordPress 开发者社区

函数文档

get_post_thumbnail_id()

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

概述

get_post_thumbnail_id() 函数用于获取文章的特色图像（Featured Image）的附件 ID。它接受一个可选的参数来指定文章，并返回 ID 或 false。

关键要点

  • 函数返回文章特色图像的附件 ID，若未设置则返回 0，若文章不存在则返回 false。
  • 参数 $post 可选，可以是文章 ID、WP_Post 对象或 null（默认使用全局 $post）。
  • 使用前需确保主题通过 add_theme_support('post-thumbnails') 启用特色图像支持。
  • “Post Thumbnail”是“Featured Image”的旧称，此函数仅返回特色图像 ID，不返回其他缩略图尺寸的附件 ID。
  • 函数内部使用 get_post_meta() 从 _thumbnail_id 元字段获取 ID，并通过 post_thumbnail_id 过滤器允许修改返回值。

代码示例

$args = array(
    'post_type'   => 'attachment',
    'numberposts' => -1,
    'post_status' => 'any',
    'post_parent' => $post->ID,
    'exclude'     => get_post_thumbnail_id(),
);

$attachments = get_posts( $args );

if ( $attachments ) {
    foreach ( $attachments as $attachment ) {
        echo apply_filters( 'the_title', $attachment->post_title );
        the_attachment_link( $attachment->ID, false );
    }
}

注意事项

  • 从 WordPress 5.5.0 开始，文章不存在时返回 false 而非空字符串。
  • 返回值通常为字符串，但函数内部强制转换为整数。
  • 设置特色图像可使用 set_post_thumbnail() 函数。
  • 在无法直接使用 get_post_thumbnail_id() 的情况下，可直接查询 _thumbnail_id 元字段。
📄 原文内容

Retrieves the post thumbnail ID.

Parameters

$postint|WP_Post|nulloptional
Post ID or WP_Post object. Default is global $post.

Default:null

Return

int|false Post thumbnail ID (which can be 0 if the thumbnail is not set), or false if the post does not exist.

More Information

  • To enable featured images, see post thumbnails, the current theme must include add_theme_support( 'post-thumbnails' ); in its functions.php file. See also Post Thumbnails.
  • “Post Thumbnail” is an outdated term for “Featured Image”. This function returns the ID of the post’s featured image. It does not return IDs of other images attached to posts that are thumbnail sized.

Source

function get_post_thumbnail_id( $post = null ) {
	$post = get_post( $post );

	if ( ! $post ) {
		return false;
	}

	$thumbnail_id = (int) get_post_meta( $post->ID, '_thumbnail_id', true );

	/**
	 * Filters the post thumbnail ID.
	 *
	 * @since 5.9.0
	 *
	 * @param int|false        $thumbnail_id Post thumbnail ID or false if the post does not exist.
	 * @param int|WP_Post|null $post         Post ID or WP_Post object. Default is global `$post`.
	 */
	return (int) apply_filters( 'post_thumbnail_id', $thumbnail_id, $post );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘post_thumbnail_id’, int|false $thumbnail_id, int|WP_Post|null $post )

Filters the post thumbnail ID.

Uses Description
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
get_post_meta()wp-includes/post.php

Retrieves a post meta field for the given post ID.
get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.

Show 1 moreShow less

Used by Description
WP_REST_Posts_Controller::prepare_links()wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Prepares links for the request.
WP_REST_Posts_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Prepares a single post output for response.
get_the_post_thumbnail_caption()wp-includes/post-thumbnail-template.php

Returns the post thumbnail caption.
get_oembed_response_data_rich()wp-includes/embed.php

Filters the oEmbed response data to return an iframe embed code.
get_the_post_thumbnail_url()wp-includes/post-thumbnail-template.php

Returns the post thumbnail URL.
WP_Media_List_Table::column_title()wp-admin/includes/class-wp-media-list-table.php

Handles the title column output.
edit_form_image_editor()wp-admin/includes/media.php

Displays the image and editor in the post editor
get_media_item()wp-admin/includes/media.php

Retrieves HTML form for modifying the image attachment.
has_post_thumbnail()wp-includes/post-thumbnail-template.php

Determines whether a post has an image attached.
update_post_thumbnail_cache()wp-includes/post-thumbnail-template.php

Updates cache for thumbnails in the current loop.
get_the_post_thumbnail()wp-includes/post-thumbnail-template.php

Retrieves the post thumbnail.
prepend_attachment()wp-includes/post-template.php

Wraps attachment in paragraph tag before content.
wp_prepare_attachment_for_js()wp-includes/media.php

Prepares an attachment post object for JS, where it is expected to be JSON-encoded and fit into an Attachment model.
wp_playlist_shortcode()wp-includes/media.php

Builds the Playlist shortcode output.
wp_xmlrpc_server::mw_getPost()wp-includes/class-wp-xmlrpc-server.php

Retrieves a post.
wp_xmlrpc_server::mw_getRecentPosts()wp-includes/class-wp-xmlrpc-server.php

Retrieves list of recent posts.
wp_xmlrpc_server::_prepare_post()wp-includes/class-wp-xmlrpc-server.php

Prepares post data for return in an XML-RPC object.

Show 12 moreShow less

Changelog

Version Description
5.5.0 The return value for a non-existing post was changed to false instead of an empty string.
4.4.0 $post can be a post ID or WP_Post object.
2.9.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

    Show all attachments for the current post except the Featured Image
    To get all post attachments except the Featured Image, you can use this function with something like get_posts().

    Do this inside The_Loop (where $post->ID is available).

    $args = array(
	'post_type'   => 'attachment',
	'numberposts' => -1,
	'post_status' => 'any',
	'post_parent' => $post->ID,
	'exclude'     => get_post_thumbnail_id(),
);

$attachments = get_posts( $args );

if ( $attachments ) {
	foreach ( $attachments as $attachment ) {
		echo apply_filters( 'the_title', $attachment->post_title );
		the_attachment_link( $attachment->ID, false );
	}
}