云策 WordPress 开发者社区

函数文档

get_the_post_thumbnail()

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

概述

get_the_post_thumbnail() 是 WordPress 核心函数，用于检索文章缩略图的 HTML 图像标签。它支持自定义图像尺寸和属性，并依赖于主题的 post-thumbnails 支持。

关键要点

  • 函数返回文章缩略图的 HTML 图像标签，默认使用 'post-thumbnail' 尺寸，但可指定其他注册尺寸或像素数组。
  • 参数包括 $post（文章 ID 或 WP_Post 对象，默认为全局 $post）、$size（图像尺寸，默认为 'post-thumbnail'）和 $attr（属性数组或字符串）。
  • 主题必须通过 add_theme_support('post-thumbnails') 启用缩略图支持，且应在 after_setup_theme 钩子前调用，以确保 init 钩子前生效。
  • 函数内部使用 wp_get_attachment_image() 生成图像标签，并应用多个过滤器和动作钩子，如 post_thumbnail_size 和 post_thumbnail_html。
  • 输出图像带有默认 CSS 类（如 wp-post-image 和基于尺寸的类），可通过 $attr 参数自定义类或其他属性。

代码示例

// 基本用法，使用默认尺寸
echo get_the_post_thumbnail( $post_id );

// 指定尺寸和自定义类
echo get_the_post_thumbnail( $post_id, 'thumbnail', array( 'class' => 'alignleft' ) );

// 使用像素数组指定尺寸
echo get_the_post_thumbnail( $post_id, array( 100, 100 ) );

注意事项

  • 确保主题已正确启用 post-thumbnails 支持，否则函数可能返回空字符串。
  • 图像尺寸参数支持 WordPress 注册的尺寸名称（如 'thumbnail', 'medium'）或宽度和高度像素数组，但实际输出可能受图像原始尺寸和比例限制。
  • 可通过 post_thumbnail_html 过滤器修改输出 HTML，例如移除宽度和高度属性或添加链接。
📄 原文内容

Retrieves the post thumbnail.

Description

When a theme adds ‘post-thumbnail’ support, a special ‘post-thumbnail’ image size is registered, which differs from the ‘thumbnail’ image size managed via the Settings > Media screen.

When using the_post_thumbnail() or related functions, the ‘post-thumbnail’ image size is used by default, though a different size can be specified instead as needed.

Parameters

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

Default:null

$sizestring|int[]optional
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default 'post-thumbnail'.
$attrstring|arrayoptional
Query string or array of attributes. Default empty.

Return

string The post thumbnail image tag.

More Information

If the required add_theme_support( 'post-thumbnails' ); in the current theme’s functions.php file is attached to a hook, it must be must be called before the init hook is fired. The init hook may be too late for some features. If attached to a hook, it must be after_setup_theme.

Source

function get_the_post_thumbnail( $post = null, $size = 'post-thumbnail', $attr = '' ) {
	$post = get_post( $post );

	if ( ! $post ) {
		return '';
	}

	$post_thumbnail_id = get_post_thumbnail_id( $post );

	/**
	 * Filters the post thumbnail size.
	 *
	 * @since 2.9.0
	 * @since 4.9.0 Added the `$post_id` parameter.
	 *
	 * @param string|int[] $size    Requested image size. Can be any registered image size name, or
	 *                              an array of width and height values in pixels (in that order).
	 * @param int          $post_id The post ID.
	 */
	$size = apply_filters( 'post_thumbnail_size', $size, $post->ID );

	if ( $post_thumbnail_id ) {

		/**
		 * Fires before fetching the post thumbnail HTML.
		 *
		 * Provides "just in time" filtering of all filters in wp_get_attachment_image().
		 *
		 * @since 2.9.0
		 *
		 * @param int          $post_id           The post ID.
		 * @param int          $post_thumbnail_id The post thumbnail ID.
		 * @param string|int[] $size              Requested image size. Can be any registered image size name, or
		 *                                        an array of width and height values in pixels (in that order).
		 */
		do_action( 'begin_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );

		if ( in_the_loop() ) {
			update_post_thumbnail_cache();
		}

		$html = wp_get_attachment_image( $post_thumbnail_id, $size, false, $attr );

		/**
		 * Fires after fetching the post thumbnail HTML.
		 *
		 * @since 2.9.0
		 *
		 * @param int          $post_id           The post ID.
		 * @param int          $post_thumbnail_id The post thumbnail ID.
		 * @param string|int[] $size              Requested image size. Can be any registered image size name, or
		 *                                        an array of width and height values in pixels (in that order).
		 */
		do_action( 'end_fetch_post_thumbnail_html', $post->ID, $post_thumbnail_id, $size );

	} else {
		$html = '';
	}

	/**
	 * Filters the post thumbnail HTML.
	 *
	 * @since 2.9.0
	 *
	 * @param string       $html              The post thumbnail HTML.
	 * @param int          $post_id           The post ID.
	 * @param int          $post_thumbnail_id The post thumbnail ID, or 0 if there isn't one.
	 * @param string|int[] $size              Requested image size. Can be any registered image size name, or
	 *                                        an array of width and height values in pixels (in that order).
	 * @param string|array $attr              Query string or array of attributes.
	 */
	return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘begin_fetch_post_thumbnail_html’, int $post_id, int $post_thumbnail_id, string|int[] $size )

Fires before fetching the post thumbnail HTML.

do_action( ‘end_fetch_post_thumbnail_html’, int $post_id, int $post_thumbnail_id, string|int[] $size )

Fires after fetching the post thumbnail HTML.

apply_filters( ‘post_thumbnail_html’, string $html, int $post_id, int $post_thumbnail_id, string|int[] $size, string|array $attr )

Filters the post thumbnail HTML.

apply_filters( ‘post_thumbnail_size’, string|int[] $size, int $post_id )

Filters the post thumbnail size.

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

Determines whether the caller is in the Loop.
get_post_thumbnail_id()wp-includes/post-thumbnail-template.php

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

Updates cache for thumbnails in the current loop.
wp_get_attachment_image()wp-includes/media.php

Gets an HTML img element representing an image attachment.
apply_filters()wp-includes/plugin.php

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

Calls the callback functions that have been added to an action hook.
get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.

Show 3 moreShow less

Used by Description
the_post_thumbnail()wp-includes/post-thumbnail-template.php

Displays the post thumbnail.

Changelog

Version Description
4.4.0 $post can be a post ID or WP_Post object.
2.9.0 Introduced.

User Contributed Notes

  1. Skip to note 13 content


    Codex


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

    Styling Post Thumbnails
    Post Thumbnails are given a class “wp-post-image”. They also get a class depending on the size of the thumbnail being displayed. You can style the output with these CSS selectors:

    img.wp-post-image
	img.attachment-thumbnail
	img.attachment-medium
	img.attachment-large
	img.attachment-full

    You can also give Post Thumbnails their own class:

    // Give the Post Thumbnail a class "alignleft".
echo get_the_post_thumbnail( $post_id, 'thumbnail', array( 'class' => 'alignleft' ) );

  2. Skip to note 14 content


    Codex


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

    Thumbnail Sizes
    The default image sizes of WordPress are “thumbnail”, “medium”, “large” and “full” (the size of the image you uploaded).
    These image sizes can be configured in the WordPress Administration Media panel under Settings > Media.
    Themes may also add “post-thumbnail”. This is how you can use these default sizes with get_the_post_thumbnail():

    // without parameter -> Post Thumbnail (as set by theme using set_post_thumbnail_size())
get_the_post_thumbnail( $post_id );                   

get_the_post_thumbnail( $post_id, 'thumbnail' );      // Thumbnail (Note: different to Post Thumbnail)
get_the_post_thumbnail( $post_id, 'medium' );         // Medium resolution
get_the_post_thumbnail( $post_id, 'large' );          // Large resolution
get_the_post_thumbnail( $post_id, 'full' );           // Original resolution

get_the_post_thumbnail( $post_id, array( 100, 100) ); // Other resolutions

    Register new image sizes for Post Thumbnails with: add_image_size().
    To set the default size for Post Thumbnails see: set_post_thumbnail_size().

  4. Skip to note 16 content


    Codex


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

    Post Thumbnail Linking to the Post Permalink

    This example shows the 5 latest Post Thumbnails linked to their Post permalink.

    $posts = get_posts( array( 'posts_per_page' => 5 ) );
foreach ( $posts as $_post ) {
	if ( has_post_thumbnail( $_post->ID ) ) {
		echo '<a href="' . get_permalink( $_post->ID ) . '" title="' . esc_attr( $_post->post_title ) . '">';
		echo get_the_post_thumbnail( $_post->ID, 'thumbnail' );
		echo '</a>';
	}
}

  5. Skip to note 17 content


    Shaikh Muhammad Arif Uddin


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

    Remove width and height attributes from the returning html

    get_the_post_thumbnail function produces html with img tag which includes width, height, src, class, alt and title attributes. The following code snippet is useful if someone wish to remove width and height attribute.

    This function provides 'post_thumbnail_html' filter before returning the html.

    add_filter( 'post_thumbnail_html', 'remove_thumbnail_width_height', 10, 5 );

function remove_thumbnail_width_height( $html, $post_id, $post_thumbnail_id, $size, $attr ) {
    $html = preg_replace( '/(width|height)="d*"s/', "", $html );
    return $html;
}

  6. Skip to note 18 content


    jesperstender


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

    You can set more than just classes –
    If you want to optimize your SrcSet values you can do something like this

     echo get_the_post_thumbnail($post->ID, 'WhateverSize-Large', array('title' => 'WhateverTitle', 'sizes' => '(max-width: 320px) 288px, (max-width: 375px) 343px, (max-width: 425px) 393px, (max-width: 540px) 493px, (max-width: 768px) 320px, (max-width: 999px) 435px, 288px'));

    etc.

    Normally in a grid, the srcset can go 100vw – which is sometimes way too big –
    this method lets you control that.

  7. Skip to note 19 content


    Codex


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

    Post Thumbnail Linking to large Image Size
    This example links to the “large” Post Thumbnail image size and must be used within The Loop.

    if ( has_post_thumbnail() ) {
	$large_image_url = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), 'large' );
	if ( ! empty( $large_image_url[0] ) ) {
		echo '<a href="' . esc_url( $large_image_url[0] ) . '" title="' . the_title_attribute( array( 'echo' => 0 ) ) . '">';
		echo get_the_post_thumbnail( $post->ID, 'thumbnail' ); 
		echo '</a>';
	}
}

  9. Skip to note 21 content


    John Dorner


    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

    When specifying a size e.g. get_the_post_thumbnail(null, [300, 300]), the image’s proportions are preserved and the width/height are maximum sizes. If the a dimension’s are smaller than specified, then the image returned will be the full size image.

    Example 1: Your image is 500px (width) by 1000px (height), the image returned will be 150px by 300px.

    Example 2: Your image is 100px by 100px the the image size returned will be 100px by 100px

  10. Skip to note 22 content


    joshcanhelp


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

    Post thumbnails in a listing context are often linked to the content they’re representing. Instead of adding that every time, here is a filter you can add that will do it automatically based on an `$attr` passed in.

    /**
 * Link thumbnails to their posts based on attr
 *
 * @param $html
 * @param int $pid
 * @param int $post_thumbnail_id
 * @param int $size
 * @param array $attr
 *
 * @return string
 */

function wpdev_filter_post_thumbnail_html( $html, $pid, $post_thumbnail_id, $size, $attr ) {

	 if ( ! empty( $attr[ 'link_thumbnail' ] ) ) {

		$html = sprintf(
			'<a href="%s" title="%s" rel="nofollow">%s</a>',
			get_permalink( $pid ),
			esc_attr( get_the_title( $pid ) ),
			$html
		);
	 }

	return $html;
}

add_filter( 'post_thumbnail_html', 'wpdev_filter_post_thumbnail_html', 10, 5 );

    Just “add the above to your functions.php file” (there’s probably a better place for it) and use it like this in a template file:

     'my-custom-class', // classes
		'link_thumbnail' => TRUE, // yes please link my thumbnail
	]
);
?>