the_attachment_link()とは？
the_attachment_link()の概要
the_attachment_link() は、WordPress の添付ファイル（画像、PDF、音声、動画など）に対するリンクをHTML形式で出力するテンプレートタグです。この関数は、主に「添付ファイルページ（attachment page）」やメディアライブラリ表示などで利用されます。
WordPress の標準機能として、画像などのメディアファイルは「添付ファイル」として投稿（attachment ポストタイプ）として扱われます。the_attachment_link() は、それらに対してリンク付きの画像やテキストを自動的に生成・出力してくれる便利な関数です。
the_attachment_link()の基本構文
the_attachment_link( int $id = 0, bool $fullsize = false, mixed $deprecated = '' )the_attachment_link()の引数の解説
| 引数 | 型 | 説明 |
|---|---|---|
$id | int | 添付ファイルの投稿ID（省略時は現在の投稿）。 |
$fullsize | bool | true の場合はフルサイズ画像を表示、false の場合はサムネイルを表示。 |
$deprecated | mixed | 廃止された引数（現在は使用されていないため無視してOK）。 |
the_attachment_link()の使い方の例
1. 現在の添付ファイルのリンクを出力
<?php the_attachment_link(); ?>このコードは、現在の投稿が添付ファイル（attachment）の場合に、その添付ファイルへのリンクを自動出力します。画像の場合、通常はサムネイル付きリンクが生成されます。
2. 指定IDの添付ファイルリンクを出力
<?php the_attachment_link( 123 ); ?>この例では、ID が 123 の添付ファイルのリンクを出力します。
3. フルサイズ画像を表示
<?php the_attachment_link( get_the_ID(), true ); ?>この場合、リンク内にはサムネイルではなくフルサイズ画像が表示されます。
the_attachment_link()の出力されるHTMLの例
<a href="https://example.com/attachment-page-url">
<img src="https://example.com/wp-content/uploads/2023/01/sample-150x150.jpg" />
</a>上記のように、リンク先は「添付ファイルページ（attachment page）」になります。
- 画像ファイル → サムネイル付きリンク
- PDFや音声 → ファイル名（またはデフォルトアイコン）付きリンク
添付ファイルページとは？
WordPressでは、画像やPDFなどをアップロードすると、それぞれに個別の「添付ファイルページ」が生成されます。このページは通常の投稿ページのようにテンプレート single-attachment.php でカスタマイズ可能です。
the_attachment_link() はこの「添付ファイルページ」へのリンクを生成します。
the_attachment_link() と wp_get_attachment_link() の違い
| 項目 | the_attachment_link() | wp_get_attachment_link() |
|---|---|---|
| 出力 | 自動で echo（表示） | 値を返す（表示はしない） |
| カスタマイズ性 | 低め | 高い（多数の引数あり） |
| 使用対象 | 単純な出力向け | より柔軟な表示を行いたいとき |
| 主な用途 | 添付ファイルページ内 | カスタムギャラリー、リスト表示 |
the_attachment_link()の注意点
1. 投稿タイプが attachment のときのみ使用可能
この関数は、添付ファイルタイプの投稿（画像やPDFなど）にのみ有効です。通常の投稿（post）や固定ページ（page）では出力されません。
2. 画像以外はテキストリンクになる
画像であれば <img> タグを含んだリンクになりますが、PDFやWordなどの非画像ファイルの場合は、ファイル名などのテキストリンクが生成されます。
the_attachment_link()のカスタマイズ方法
the_attachment_link() は出力内容を直接カスタマイズすることが難しいため、より柔軟な制御を行いたい場合は wp_get_attachment_link() を使うのが一般的です。
ただし、フィルターフック wp_get_attachment_link は the_attachment_link() 内部でも利用されているため、そこを通じて間接的にカスタマイズが可能です。
add_filter( 'wp_get_attachment_link', 'custom_attachment_link', 10, 6 );
function custom_attachment_link( $link, $id, $size, $permalink, $icon, $text ) {
return '<div class="custom-attachment">' . $link . '</div>';
}添付ファイルを一覧で表示する例
$attachments = get_posts(array(
'post_type' => 'attachment',
'numberposts' => -1,
'post_status' => 'inherit'
));
if ( $attachments ) {
foreach ( $attachments as $attachment ) {
echo '<li>';
the_attachment_link( $attachment->ID );
echo '</li>';
}
}このコードで、すべての添付ファイルのリンクがリスト形式で出力されます。
the_attachment_link()の利用ケースまとめ
| 利用シーン | 内容 |
|---|---|
| 添付画像の表示 | 投稿にアップロードされた画像をリンク付きで表示 |
| PDF等ファイルへのリンク | メディアライブラリにアップロードされた文書へのリンク生成 |
| 添付ファイルページのカスタマイズ | single-attachment.php で装飾や説明文追加が可能 |
| メディアギャラリーの簡易表示 | get_children() と組み合わせて一覧表示 |
the_attachment_link()のまとめ
| 項目 | 内容 |
|---|---|
| 関数名 | the_attachment_link() |
| 用途 | 添付ファイルへのリンクをHTML形式で出力 |
| 出力内容 | <a> タグで囲んだ画像またはテキストリンク |
| リンク先 | 添付ファイルページ（single-attachment.php） |
| カスタマイズ性 | 制限あり。フィルターで対応可 |
| 画像以外 | テキストリンク（PDFや音声など） |
| 代替関数 | wp_get_attachment_link()（返り値形式） |
the_attachment_link() は、画像やメディアファイルのリンクを簡単に出力したいときに便利なテンプレートタグです。特に画像ギャラリーやメディアライブラリ一覧、添付ファイルページでの表示に適しています。
ただし、カスタマイズ性には限界があるため、柔軟な表示が必要な場合は wp_get_attachment_link() への移行も検討するとよいでしょう。
