the_post_thumbnail() - WordPress 函数参考中文文档



发布于 2017-09-11 字数8530 浏览 954 评论 0

the_post_thumbnail( string|array $size = 'post-thumbnail',  string|array $attr = '' )

Display the post thumbnail.


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 相关函数 functions, the ‘post-thumbnail’ image size is used by default, though a different size can be specified instead as needed.



Image size to use. Accepts any valid image size, or an array of width and height values in pixels (in that order).

Default value: ‘post-thumbnail’


Query string or array of attributes.

Default value: ”


File: wp-includes/post-thumbnail-template.php

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


Version 描述
2.9.0 Introduced.

More Information


the_post_thumbnail( $size, $attr );



  • wp-includes/post-thumbnail-template.php:

User Contributed Notes

  1. Skip to note content

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

    Contributed by shramee

    Post thumbnail sizes:

    //Default WordPress
    the_post_thumbnail( 'thumbnail' );     // Thumbnail (150 x 150 hard cropped)
    the_post_thumbnail( 'medium' );        // Medium resolution (300 x 300 max height 300px)
    the_post_thumbnail( 'medium_large' );  // Medium Large (added in WP 4.4) resolution (768 x 0 infinite height)
    the_post_thumbnail( 'large' );         // Large resolution (1024 x 1024 max height 1024px)
    the_post_thumbnail( 'full' );          // Full resolution (original size uploaded)
    //With WooCommerce
    the_post_thumbnail( 'shop_thumbnail' ); // Shop thumbnail (180 x 180 hard cropped)
    the_post_thumbnail( 'shop_catalog' );   // Shop catalog (300 x 300 hard cropped)
    the_post_thumbnail( 'shop_single' );    // Shop single (600 x 600 hard cropped)

    Hard cropped sizes have fixed height and width

  2. An example of the attr argument using an array can be seen below:

    the_post_thumbnail('post-thumbnail', ['class' => 'img-responsive responsive--full', 'title' => 'Feature image']);

    Using the array’s keys and values to populate different attributes. You can use this to add classes to the post thumbnail.

    Post Thumbnail Linking to the Post Permalink

    Note: Don’t use these two examples together in the same Theme.

    Example 1. To link Post Thumbnails to the Post Permalink in a specific loop, use the following within your Theme’s template files:

    <?php if ( has_post_thumbnail() ) : ?>
    	<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
    		<?php the_post_thumbnail(); ?>
    <?php endif; ?>

    Example 2. To link all Post Thumbnails on your website to the Post Permalink, put this in the current Theme’s functions.php file:

     * Link all post thumbnails to the post permalink.
     * @param string $html          Post thumbnail HTML.
     * @param int    $post_id       Post ID.
     * @param int    $post_image_id Post image ID.
     * @return string Filtered post image HTML.
    function wpdocs_post_image_html( $html, $post_id, $post_image_id ) {
    	$html = '<a href="' . get_permalink( $post_id ) . '" alt="' . esc_attr( get_the_title( $post_id ) ) . '">' . $html . '</a>';
    	return $html;
    add_filter( 'post_thumbnail_html', 'wpdocs_post_image_html', 10, 3 );

    Styling Post Thumbnails

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


    You can also give Post Thumbnails their own class.
    Display the Post Thumbnail with a class “alignleft”:

    the_post_thumbnail( 'thumbnail', array( 'class' => 'alignleft' ) ); 

    Default Usage

    // Check if the post has a Post Thumbnail assigned to it.
    if ( has_post_thumbnail() ) {

    Note: To return the Post Thumbnail for use in your PHP code instead of displaying it, use: get_the_post_thumbnail().

    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. This is how you can use these default sizes with the_post_thumbnail():

    the_post_thumbnail();                  // without parameter -> 'post-thumbnail'
    the_post_thumbnail( 'thumbnail' );       // Thumbnail (default 150px x 150px max)
    the_post_thumbnail( 'medium' );          // Medium resolution (default 300px x 300px max)
    the_post_thumbnail( 'large' );           // Large resolution (default 640px x 640px max)
    the_post_thumbnail( 'full' );            // Full resolution (original size uploaded)
    the_post_thumbnail( 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().


    $attr = array(
        'src'   => $src,
        'class' => "your-css-class",
        'alt'   => "your alt text"

    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(), 'large' );
    	if ( ! empty( $large_image_url[0] ) ) {
    		printf( '<a href="%1$s" alt="%2$s">%3$s</a>',
    			esc_url( $large_image_url[0] ),
    			esc_attr( get_the_title_attribute( 'echo=0' ) ),

    If you’d like to remove the hardcoding of the ‘height’ and ‘width’ attributes on thumbnail images, which will often effect adaptive/responsive/fluid CSS stylesheets, you can add this snippet to your functions.php,

    // remove width & height attributes from images
    function remove_img_attr ($html)
        return preg_replace('/(width|height)="\d+"\s/', "", $html);
    add_filter( 'post_thumbnail_html', 'remove_img_attr' );

    See Also:


需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。