get_the_post_thumbnail() の使い方｜説明・引数・注意点

説明

基本構文

get_the_post_thumbnail( int|WP_Post $post = null, string|int[] $size = 'post-thumbnail', string|array $attr = '' ): string

引数

• $post：投稿IDまたはオブジェクト
• $size：画像サイズ
• $attr：img タグの属性

戻り値

img タグの文字列。アイキャッチがなければ空文字。

使い方（サンプル）

echo get_the_post_thumbnail( 123, 'large' );

注意点

• タグ全体が返るため、URLだけが欲しいときは get_the_post_thumbnail_url() を使います。

実務での使いどころ

• アイキャッチ画像のimgタグを、文字列として受け取りたいとき。
• 投稿IDを指定して、ループの外から取得するとき。

よくあるミスと対処

• 戻り値を echo し忘れている。この関数は出力せず、文字列を返す。
• アイキャッチ画像が未設定のとき、空文字が返る。has_post_thumbnail() で確認する。
• サイズ名を間違えている。登録されていない名前では、意図したサイズにならない。

NG例

get_the_post_thumbnail( $post_id, 'medium' ); // 返すだけで、出力されない

OK例

echo get_the_post_thumbnail( $post_id, 'medium' );

使い分け早見表

関連項目

the_post_thumbnail()、get_the_post_thumbnail_url()、has_post_thumbnail()

公式リファレンス：get_the_post_thumbnail() | Function | WordPress Developer Resources