目次
the_post_thumbnail()とは？
the_post_thumbnail() は、WordPress におけるアイキャッチ画像（サムネイル画像）を表示するためのテンプレートタグです。主にテーマファイル内で使用され、投稿や固定ページに設定されたアイキャッチ画像を HTML の <img> タグとして出力します。
この関数は、表示の自由度と簡潔さを兼ね備えており、カスタムサイズの指定や HTML クラスの追加など、柔軟なカスタマイズが可能です。
the_post_thumbnail()の基本構文
the_post_thumbnail( string|array $size = 'post-thumbnail', string|array $attr = '' )the_post_thumbnail()の引数
| 引数 | 型 | 説明 |
|---|---|---|
$size | string または array | 出力する画像サイズ（例：'thumbnail', 'medium', 'large', 'full' など）または [幅, 高さ] の配列 |
$attr | string または array | <img> タグに追加する HTML 属性（例：class, alt, loading など） |
the_post_thumbnail()の戻り値
なし（直接 <img> タグを出力）
the_post_thumbnail()の使い方の例
1. デフォルトのサムネイルを表示
if ( has_post_thumbnail() ) {
the_post_thumbnail();
}この場合、テーマ側で指定されている 'post-thumbnail' サイズ（通常は medium）で画像が表示されます。
2. サイズを指定して表示
the_post_thumbnail('large'); // large サイズで表示
the_post_thumbnail('thumbnail'); // thumbnail サイズで表示
the_post_thumbnail('full'); // 元サイズで表示3. 任意サイズ（配列で指定）
the_post_thumbnail([300, 200]);→ 幅300px、高さ200pxのサイズに切り抜かれた画像を表示します。
4. HTML 属性を追加
the_post_thumbnail('medium', ['class' => 'custom-class', 'alt' => '代替テキスト']);→ 出力される <img> タグに class や alt を付与できます。
the_post_thumbnail()の出力例
以下のような HTML が出力されます：
<img width="600" height="400" src="https://example.com/wp-content/uploads/2023/01/sample.jpg" class="attachment-large size-large wp-post-image" alt="" />※ クラス名には自動的に attachment-サイズ名、size-サイズ名、wp-post-image が付与されます。
よく使うサイズ指定
WordPress には以下の標準画像サイズがあります（functions.php で変更可）：
| サイズ名 | 初期設定のサイズ | 用途 |
|---|---|---|
'thumbnail' | 150×150（トリミングあり） | 一覧表示などの小サイズ |
'medium' | 300×300（トリミングなし） | 記事本文内の画像など |
'large' | 1024×1024（トリミングなし） | ヘッダー画像、記事上部など |
'full' | アップロード元の元画像サイズ | 最大サイズでの表示 |
'post-thumbnail' | テーマで使用する代表画像サイズ | テーマで自由に設定可能 |
独自サイズの登録と利用
1. サイズの登録（functions.php）
add_image_size( 'custom-thumb', 400, 250, true ); // true = トリミングあり2. 表示時に使う
the_post_thumbnail('custom-thumb');the_post_thumbnail()の注意点
1. 使用前にアイキャッチ画像機能の有効化が必要
functions.php に以下を追加：
add_theme_support('post-thumbnails');2. アイキャッチ画像が未設定の場合は何も出力されない
そのため、通常は has_post_thumbnail() と組み合わせて使います：
if ( has_post_thumbnail() ) {
the_post_thumbnail('medium');
}the_post_thumbnail()の応用例
1. 一覧ページでアイキャッチとタイトルを表示
<?php if ( have_posts() ) : ?>
<?php while ( have_posts() ) : the_post(); ?>
<div class="post-item">
<?php if ( has_post_thumbnail() ) : ?>
<a href="<?php the_permalink(); ?>">
<?php the_post_thumbnail('thumbnail'); ?>
</a>
<?php endif; ?>
<h2><?php the_title(); ?></h2>
</div>
<?php endwhile; ?>
<?php endif; ?>2. srcset によるレスポンシブ画像
WordPressはデフォルトで srcset 属性を自動生成します：
<img src="image-300.jpg"
srcset="image-300.jpg 300w, image-600.jpg 600w, image-900.jpg 900w"
sizes="(max-width: 600px) 100vw, 600px" />→ これにより、デバイスに応じて最適なサイズの画像が自動で表示されます。
the_post_thumbnail()のよくある間違いと対処法
| 問題 | 原因 | 解決策 |
|---|---|---|
| 画像が表示されない | アイキャッチ画像が設定されていない | has_post_thumbnail() を使って確認 |
| サイズがおかしい | 指定サイズが未登録 | add_image_size() で登録し、regenerate thumbnails プラグインで再生成 |
| alt 属性が空になる | 明示的に指定していない | $attr 配列で 'alt' => '説明文' を追加 |
関連関数との違い
| 関数名 | 説明 |
|---|---|
the_post_thumbnail() | 画像をHTMLで出力する |
get_the_post_thumbnail() | 画像のHTMLを文字列として返す（出力はしない） |
get_post_thumbnail_id() | アイキャッチ画像の attachment ID を取得する |
has_post_thumbnail() | アイキャッチ画像が設定されているか判定する |
set_post_thumbnail() | 投稿にアイキャッチ画像を設定する（IDで） |
the_post_thumbnail()のまとめ
the_post_thumbnail()は、アイキャッチ画像を HTML の<img>タグで出力するテンプレートタグ。- サイズや属性の指定により柔軟なカスタマイズが可能。
- 使用前に
add_theme_support('post-thumbnails')が必要。 has_post_thumbnail()との組み合わせで安全に使用。add_image_size()によって独自の画像サイズも利用可能。
