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

説明

基本構文

the_post_thumbnail( string|int[] $size = 'post-thumbnail', string|array $attr = '' ): void

引数

• $size：画像サイズ名、または array( 幅, 高さ )
• $attr：img タグに付与する属性

戻り値

戻り値はありません（出力します）。

使い方（サンプル）

if ( has_post_thumbnail() ) {
	the_post_thumbnail( 'medium', array( 'class' => 'thumb' ) );
}

注意点

• テーマで add_theme_support( 'post-thumbnails' ) を有効にする必要があります。
• アイキャッチが無いと何も出力されないため、has_post_thumbnail() で確認します。

実務での使いどころ

• アイキャッチ画像を、そのまま出力するとき。
• 画像サイズを指定して出力するとき（the_post_thumbnail( 'medium' )）。

よくあるミスと対処

• テーマで add_theme_support( 'post-thumbnails' ) を呼んでいない。アイキャッチ画像が使えない。
• アイキャッチ画像が未設定の投稿では、何も出力されない。代替画像が必要なら、has_post_thumbnail() で分岐する。
• 出力ではなく、値として使いたいのに、これを使っている。値は get_the_post_thumbnail() を使う。

NG例

the_post_thumbnail( 'medium' ); // 未設定の投稿では、何も出ない

OK例

if ( has_post_thumbnail() ) {
	the_post_thumbnail( 'medium' );
} else {
	echo '<img src="' . esc_url( get_theme_file_uri( '/img/noimage.png' ) ) . '" alt="">';
}

使い分け早見表

関連項目

get_the_post_thumbnail()、has_post_thumbnail()、wp_get_attachment_image()

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