ワードプレスのthe_post_thumbnailフィルタの使用方法・解説

概要

the_post_thumbnailフィルタは、アイキャッチ画像を表示する際に使われる重要なフィルタです。このフィルタを利用することで、アイキャッチ画像の出力をカスタマイズしたり、新しい属性を追加したりすることが可能となります。一般的に、このフィルタは次のような機能を実装する際に使用されます。

1. アイキャッチ画像のクラスを追加する
2. 画像のサイズを変更する
3. レスポンシブ画像を生成する
4. 画像のラッパー要素を追加する
5. 特定の条件に基づいて画像を変更する
6. 外部サービスから取得した画像を使用する
7. 画像にカスタムデータ属性を追加する
8. SEO向けに画像にalt属性を追加する

構文

add_filter('post_thumbnail_html', 'your_custom_function', 10, 5);

パラメータ

• $html: アイキャッチ画像のHTMLコード
• $post_id: 投稿のID
• $post_thumbnail_id: アイキャッチ画像のID
• $size: 画像サイズ
• $attr: 画像に関する属性

戻り値

• カスタマイズされたアイキャッチ画像のHTMLコード

関連する関数

post_thumbnail_html

使用可能なバージョン

WordPress 2.9 以降

コアファイルのパス

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: アイキャッチ画像にカスタムクラスを追加

このコードは、アイキャッチ画像にカスタムクラスを追加する例です。

add_filter('post_thumbnail_html', 'add_custom_class_to_thumbnail', 10, 5);
function add_custom_class_to_thumbnail($html, $post_id, $post_thumbnail_id, $size, $attr) {
    return str_replace('class="', 'class="custom-class ', $html);
}

出典: WordPress Codex

サンプルコード2: アイキャッチ画像サイズの変更

アイキャッチ画像のサイズを変更するためのコードです。

add_filter('post_thumbnail_html', 'change_thumbnail_size', 10, 5);
function change_thumbnail_size($html, $post_id, $post_thumbnail_id, $size, $attr) {
    $custom_size = 'medium'; // カスタムサイズを指定
    $new_html = wp_get_attachment_image($post_thumbnail_id, $custom_size, false, $attr);
    return $new_html;
}

出典: WordPress Forum

サンプルコード3: 画像にalt属性を追加

アイキャッチ画像にalt属性を追加するサンプルです。

add_filter('post_thumbnail_html', 'add_alt_attribute_to_thumbnail', 10, 5);
function add_alt_attribute_to_thumbnail($html, $post_id, $post_thumbnail_id, $size, $attr) {
    $alt_text = get_post_meta($post_thumbnail_id, '_wp_attachment_image_alt', true);
    return str_replace('alt=""', 'alt="' . esc_attr($alt_text) . '"', $html);
}

出典: WPBeginner

サンプルコード4: アイキャッチ画像のラッパー要素を追加

アイキャッチ画像にラッパーを追加するためのサンプルコードです。

add_filter('post_thumbnail_html', 'wrap_thumbnail_with_div', 10, 5);
function wrap_thumbnail_with_div($html, $post_id, $post_thumbnail_id, $size, $attr) {
    return '<div class="thumbnail-wrapper">' . $html . '</div>';
}

出典: CSS-Tricks

サンプルコード5: アイキャッチ画像の条件付き表示

特定の条件に基づいてアイキャッチ画像を表示する例です。

add_filter('post_thumbnail_html', 'conditional_thumbnail_display', 10, 5);
function conditional_thumbnail_display($html, $post_id, $post_thumbnail_id, $size, $attr) {
    if (is_single() && get_post_type($post_id) === 'post') {
        return $html; // 投稿の単一ページでは表示
    }
    return ''; // その他のページでは表示しない
}

出典: ThemeShaper