開発ブログ

WWWクリエイターズが送る、Git、CSS、HTML、コマンドライン、Macの便利機能など、開発に関する役立ち情報発信します。気まぐれに更新。

WordPress: アイキャッチ画像URLの取得方法、2017年版!

最終更新:2017-07-23 by Joe

WordPressで、投稿のアイキャッチ画像のURL(文字列)を一発で取得する関数「get_the_post_thumbnail_url」が、Wordpress version4.4 でついにリリースされました!

やった〜。なんでいままでなかったのでしょうか。

胸のつかえが取れた気分です。

アイキャッチ画像のURLを出力する関数

まずは関数です。ズバリ:the_post_thumbnail_url

// アイキャッチ画像のURL文字列を出力する
the_post_thumbnail_url( 'medium' );

サイズは、’thumbnail’, ‘medium’, ‘large’, ‘full’, などなど、好きにしてください。

引数で投稿IDを渡せないのは、不便ですが、the_xxxxの、theで始まる関数は、メインループ内での利用を意図されているということでしょう。(the_contentとかも、そうです。)

アイキャッチ画像のURLを取得する関数

こちらはURLの文字列を取得するだけで、出力しない場合です。こちらは投稿IDを渡すことができ、汎用的に使えます。

get_the_post_thumbnail_url( get_the_ID(), 'medium' );

上記の例では、get_the_ID()は、グローバルの$postオブジェクトがセットアップされている状態で使って下さいね、(もしくは適宜、必要な投稿IDを引数入れてください。)

おそらく多くの場合は、最初のthe_post_thumbnail_urlで、「URL文字列を出力する」の関数を使う場面が、多いのではないかと思います。

ソースコードを確認

実際の関数のソースコードは、/wp-includes/post-thumbnail-template.php にあります:

/**
 * Return the post thumbnail URL.
 *
 * @since 4.4.0
 *
 * @param int|WP_Post  $post Optional. Post ID or WP_Post object.  Default is global `$post`.
 * @param string|array $size Optional. Registered image size to retrieve the source for or a flat
 *                           array of height and width dimensions. Default 'post-thumbnail'.
 * @return string|false Post thumbnail URL or false if no URL is available.
 */
function get_the_post_thumbnail_url( $post = null, $size = 'post-thumbnail' ) {
	$post_thumbnail_id = get_post_thumbnail_id( $post );
	if ( ! $post_thumbnail_id ) {
		return false;
	}
	return wp_get_attachment_image_url( $post_thumbnail_id, $size );
}

/**
 * Display the post thumbnail URL.
 *
 * @since 4.4.0
 *
 * @param string|array $size Optional. Image size to use. Accepts any valid image size,
 *                           or an array of width and height values in pixels (in that order).
 *                           Default 'post-thumbnail'.
 */
function the_post_thumbnail_url( $size = 'post-thumbnail' ) {
	$url = get_the_post_thumbnail_url( null, $size );
	if ( $url ) {
		echo esc_url( $url );
	}
}

このバージョンは2015年12月8日に公開されたようです:
https://wpdocs.osdn.jp/Version_4.4

この関数が存在しなかった時代

これまでのワードプレスでのアイキャッチ画像の取得方法は、なんだかすっきりしないものでした。

それは、<img>タグにURLが埋め込まれた状態で取得する関数です。

// アイキャッチ画像を<img>タグで取得する
get_the_post_thumbnail( get_the_ID(), 'medium' );

実際は、上記の関数のように、URLの文字列だけ欲しい事、よくありますよね。

過去は、「URLだけ」を取得しようとすると、なんとも回りくどい方法を自分で記述するしかありませんでした。

// もしアイキャッチ画像が設定されていれば・・
if ( has_post_thumbnail() ) {

  // Attachment投稿の投稿IDを取得
  $image_id = get_post_thumbnail_id();

  // Attachment投稿から、urlの文字列値を取得
  $image_url = wp_get_attachment_image_src ($image_id, true);

  // 0:URL, 1:Width, 2:Height
  echo $image_url[0];
}

一応参考です。

上記、 get_the_post_thumbnail()のDevサイトページのコメントにhas_post_thumbnail()に期待されない振る舞いがあることを指摘していますね。

has_post_thumbnailという関数名なのに、アイキャッチが設定されていなくてもtrueを返すようです。アイキャッチが設定されていなくてもなくても、記事の先頭にあるimgタグを自動で見つけて、返してくれるもともとのWordpressの仕様が影響していそうです。ここはワードプレスのちょっと細かい話ですね。

Post Thumbnailの豆知識・歴史

もともと、投稿にアイキャッチ画像を設定するための「Post thumbnails」の機能自体は、version2.9でリリースされ、その後すぐに3.0で、「feature images」という名前に変更されたようです。(参考

この名前変更に関して、その頃は、私もまだWordPressについて詳しく知らなかったので、細かい理由はよくわかりませんが、おそらく「サムネール」て「親指の爪」くらい小さな画像の事をそう呼ぶのに対して、実際の画像の用途が全然サムネールじゃなく、多岐に渡る。名前が適切ではないのではないか?というあたりではないでしょう。

おかげで、今や関数名と実際の呼び名がずれてちょっとわかりにくくなってます。「アイキャッチ画像」とう日本語訳も、かなりもともとの英語とニュアンスが離れてしまっていますね・・・。

所感

なぜこの関数が、WordPress ver4.4のタイミングまで追加されなかったのかはよく知りませんが、多くのテーマ開発者は、自作の関数でやりくりしてたのではないでしょうか。やはりURLを文字列で取得したいタイミングは多いです。

ようやく公式の関数ができたので、安心して使えますね。

参考リンク

役立つCodex(英語)はこちら:
https://codex.wordpress.org/Function_Reference/the_post_thumbnail_url

コーデックス日本語版はまだないみたいです。筆者も、もしあとで時間ができたら書いておきます。

 

 

閉じる