概要
get_the_post_thumbnail_url 関数は、WordPress で投稿のアイキャッチ画像（サムネイル）のURLを取得するために使用されます。この関数は、テーマのカスタマイズやプラグインの開発において、特定の投稿に関連付けられたサムネイル画像を表示する必要がある場面で役立ちます。具体的には、以下のようなシナリオでよく使用されます。
- 投稿の詳細ページでサムネイルを表示したいとき
- サムネイルを使用してカスタムクエリの結果を一覧表示するとき
- ウィジェットやショートコードでアイキャッチ画像を使用する際
- サムネイルをCSSスタイルで背景画像として使用するとき
- JavaScriptの動的な内容でサムネイルを利用するとき
- 投稿のリスト表示でアイキャッチ画像を含めたいとき
- カスタム投稿タイプのアイキャッチ画像を取得する際
- 投稿のメタデータと共に表示する画像を取得したいとき
構文
get_the_post_thumbnail_url( $post_id, $size );
パラメータ
$post_id（int）: 画像のサムネイルを取得する投稿のID。省略した場合は現在の投稿が使用されます。$size（string|array）: 取得したい画像サイズ。’thumbnail’, ‘medium’, ‘large’, ‘full’ などのサイズ名を指定できます。
戻り値
- 取得したアイキャッチ画像のURL（string）。該当するサムネイルが設定されていない場合は、
nullが返されます。
関連する関数
使用可能なバージョン
- この関数は、WordPress 3.0 以降で利用可能です。
コアファイルのパス
wp-includes/post-thumbnail-template.php
この関数のアクションでの使用可能性
| アクション | 使用例 |
|---|---|
| mu_plugin_loaded | |
| registered_post_type | |
| plugins_loaded | |
| wp_roles_init | |
| setup_theme | |
| after_setup_theme | |
| set_current_user | |
| init | |
| register_sidebar | |
| wp_loaded | |
| send_headers | |
| parse_query | |
| pre_get_posts | |
| wp | 〇 |
| template_redirect | 〇 |
| get_header | 〇 |
| wp_head | 〇 |
サンプルコード
サンプルコード1: 特定の投稿のアイキャッチ画像URLを取得
$post_id = 1; // 投稿IDを指定
$thumbnail_url = get_the_post_thumbnail_url($post_id);
echo $thumbnail_url; // URLを出力
このコードは、指定した投稿IDに基づいて、その投稿のアイキャッチ画像のURLを取得し、出力します。
サンプルコード2: カスタムサイズのアイキャッチ画像を取得
$thumbnail_url = get_the_post_thumbnail_url(null, 'medium'); // 現在の投稿の中サイズサムネイルを取得
if ($thumbnail_url) {
echo '<img src="' . esc_url($thumbnail_url) . '" alt="サムネイル画像">';
}
このコードは、現在の投稿の中サイズのアイキャッチ画像を取得し、存在する場合はその画像を表示します。
サンプルコード3: アイキャッチ画像のURLを条件に埋め込む
if (has_post_thumbnail()) {
$thumbnail_url = get_the_post_thumbnail_url(); // 現在の投稿のアイキャッチ画像のURL
echo '<div style="background-image: url(' . esc_url($thumbnail_url) . '); height: 300px;"></div>';
}
このコードは、投稿のアイキャッチ画像が設定されている場合に、背景画像としてそのURLを使用します。
サンプルコード4: 投稿のリストでアイキャッチ画像を表示
$args = array('post_type' => 'post', 'posts_per_page' => 5);
$posts = new WP_Query($args);
if ($posts->have_posts()) {
while ($posts->have_posts()) {
$posts->the_post();
$thumbnail_url = get_the_post_thumbnail_url();
echo '<h2>' . get_the_title() . '</h2>';
if ($thumbnail_url) {
echo '<img src="' . esc_url($thumbnail_url) . '" alt="' . get_the_title() . '">';
}
}
}
wp_reset_postdata();
このコードは最新の5つの投稿を取得し、それぞれの投稿についてタイトルとアイキャッチ画像を表示します。
サンプルコード5: JSONレスポンスにサムネイルを含める
add_action('rest_api_init', function() {
register_rest_route('custom/v1', '/posts/', array(
'methods' => 'GET',
'callback' => function() {
$posts = get_posts(array('numberposts' => 5));
$data = array();
foreach ($posts as $post) {
$data[] = array(
'title' => get_the_title($post->ID),
'thumbnail' => get_the_post_thumbnail_url($post->ID)
);
}
return $data;
}
));
});
このコードは、カスタムREST APIエンドポイントを作成し、最新5つの投稿のタイトルとアイキャッチ画像のURLをJSON形式で返します。
引用元はそれぞれのコードに準じており、すべて著作権フリーのコードです。