get_the_post_thumbnail_url()
云策文档标注
概述
get_the_post_thumbnail_url() 函数用于获取文章特色图片的 URL。它接受可选参数来指定文章和图片尺寸，并返回 URL 字符串或 false。
关键要点
- 函数返回文章特色图片的 URL，若无图片则返回 false
- 参数 $post 可选，可为文章 ID、WP_Post 对象或 null（默认使用全局 $post）
- 参数 $size 可选，指定注册的图片尺寸或宽高数组，默认为 'post-thumbnail'
- 若 $size 不匹配任何注册尺寸，则返回原始图片 URL
- 通过 apply_filters('post_thumbnail_url', ...) 提供过滤器钩子
代码示例
// 在循环内使用，获取全尺寸特色图片 URL
$featured_img_url = get_the_post_thumbnail_url(get_the_ID(), 'full');
// 在循环外使用，指定文章 ID
$post = get_post(2);
$featured_img_url = get_the_post_thumbnail_url($post->ID, 'full');注意事项
- 函数返回字符串或 false，不是对象，无法直接访问图片 ID
- 若上传图片小于请求尺寸，会返回原始图片而非 false
- 需正确传递参数顺序：第一个参数为文章，第二个为尺寸
原文内容
Returns the post thumbnail URL.
Parameters
Source
function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
$post_thumbnail_id = get_post_thumbnail_id( $post );
if ( ! $post_thumbnail_id ) {
return false;
}
$thumbnail_url = wp_get_attachment_image_url( $post_thumbnail_id, $size );
/**
* Filters the post thumbnail URL.
*
* @since 5.9.0
*
* @param string|false $thumbnail_url Post thumbnail URL or false if the post does not exist.
* @param int|WP_Post|null $post Post ID or WP_Post object. Default is global `$post`.
* @param string|int[] $size Registered image size to retrieve the source for or a flat array
* of height and width dimensions. Default 'post-thumbnail'.
*/
return apply_filters( 'post_thumbnail_url', $thumbnail_url, $post, $size );
}
Hooks
- apply_filters( ‘post_thumbnail_url’, string|false $thumbnail_url, int|WP_Post|null $post, string|int[] $size )
-
Filters the post thumbnail URL.
Changelog
| Version | Description |
|---|---|
| 4.4.0 | Introduced. |
Skip to note 5 content
codeunderground
Don’t ignore the first parameter.
Proper usage of `get_the_post_thumbnail_url() ` inside the loop:
if ( have_posts() ) { while ( have_posts() ) { the_post(); /* grab the url for the full size featured image */ $featured_img_url = get_the_post_thumbnail_url(get_the_ID(),'full'); /* link thumbnail to full size image for use with lightbox*/ echo '<a href="'.esc_url($featured_img_url).'" rel="lightbox">'; the_post_thumbnail('thumbnail'); echo '</a>'; endwhile; endif;Skip to note 6 content
Raul P.
It’s worth to note that, if you upload a smaller image (let’s say, a 600px wide) and use this to fetch a specific larger image (let’s say, a 1920px wide for your cover), it will return the original image instead (which is smaller than what you need) instead of returning false.
If you need to fallback to another image in case the specified file doesn’t exist, you can look into wp_get_attachment_image_src instead, and check for the width or height of the image.
Skip to note 7 content
LindsayMac
Downvoted the example posted from @thelilmercoder as it is not proper usage of this function.
Proper usage of `
get_the_post_thumbnail_url()` inside the loop:if ( have_posts() ) { while ( have_posts() ) { the_post(); /* grab the url for the full size featured image */ $featured_img_url = get_the_post_thumbnail_url('full'); /* link thumbnail to full size image for use with lightbox*/ echo '<a href="'.$featured_img_url.'" rel="lightbox">'; the_post_thumbnail('thumbnail'); echo '</a>'; endwhile; endif;Proper usage of `
get_the_post_thumbnail_url()` outside the loop:/* get a specific post object by ID */ $post = get_post(2); /* grab the url for the full size featured image */ $featured_img_url = get_the_post_thumbnail_url($post->ID, 'full'); /* link thumbnail to full size image for use with lightbox*/ echo '<a href="'.$featured_img_url.'" rel="lightbox">'; the_post_thumbnail('thumbnail'); echo '</a>';get_the_post_thumbnail_url()inside the loop:. The first argument ofget_the_post_thumbnail_url()should be the post ID or object, not the image size. You might want to addget_the_ID()before ‘full’ argument to get the full-size featured image URL.Skip to note 8 content
Rose
To display the featured image with the alt tag use something like this
$thumbnail = get_the_post_thumbnail_url(); if ( $thumbnail ) { $alt_text = get_post_meta( $thumbnail->ID, '_wp_attachment_image_alt', true ); if ( ! empty( $thumbnail ) ) { if ( ! empty( $alt_text ) ) { $alt_text = $alt_text; } else { $alt_text = __( 'no alt text set', 'textdomain' ); } echo ''; } }get_the_post_thumbnail_url()function return a thumbnail URL as string or false on error. So, you can’t access media ID through$thumbnail->ID. This code has error.$thumbnailwill return the URL (string), not the image object. This won’t work. You could try to useattachment_url_to_postid( $thumbnail )to try and get the attachment ID.