קבלת הקישור לתמונה הראשית (featured image url)

כדי לקבל את הקישור (URL) לתמונה הראשית (featured image) בוורדפרס, השתמשו בפונקציה get_the_post_thumbnail_url(). היא מחזירה רק את כתובת התמונה, ולא תגית <img> מלאה, וזה בדיוק מה שאתם צריכים עבור background-image ב-CSS, תגית Open Graph או סליידר ב-JavaScript.

לעומת זאת, הפונקציה get_the_post_thumbnail() מחזירה את אלמנט התמונה המלא, והיא הבחירה הנכונה כשאתם רוצים תגית <img> עם srcset. כשאתם צריכים רק את הכתובת, השתמשו בסניפטים הבאים.

קבלת הקישור לתמונה הראשית

הוסיפו את הקוד הבא בתוך הלולאה של וורדפרס, בקובץ תבנית כמו single.php או ב-template part:

<?php
if ( has_post_thumbnail() ) {
    $thumb_url = get_the_post_thumbnail_url( get_the_ID(), 'large' );
    ?>
    <div class="post-hero" style="background-image: url('<?php echo esc_url( $thumb_url ); ?>');"></div>
    <?php
}
?>

המשתנה $thumb_url יכיל את הקישור לתמונה הראשית של הפוסט הנוכחי בגודל large.

איך זה עובד?

הפונקציה get_the_post_thumbnail_url( $post, $size ) קיימת בליבת וורדפרס מאז גרסה 4.4 (ראו את התיעוד של הפונקציה). שני הפרמטרים אופציונליים:

• $post: מזהה (ID) של פוסט או אובייקט WP_Post. כברירת מחדל, הפוסט הגלובלי שבלולאה.
• $size: שם רשום של גודל תמונה, כמו thumbnail, medium, large או full, או מערך של רוחב וגובה. ברירת המחדל היא post-thumbnail.

הפונקציה מחזירה false אם לפוסט אין תמונה ראשית, לכן בדקו קודם עם has_post_thumbnail().

אם שם הגודל לא רשום, וורדפרס מחזירה את הכתובת של התמונה המקורית. ראו גם את הפוסט איך לשלוט בגודל התמונות בוורדפרס (Image Sizes) כדי להוסיף גדלים משלכם.

כדי להדפיס את הכתובת ישירות, the_post_thumbnail_url( 'large' ) מדפיסה אותה לאחר שכבר עברה escaping. שימו לב שהתיבה ״תמונה ראשית״ (Featured Image) מופיעה בעורך רק אם התבנית שלכם מצהירה על add_theme_support( 'post-thumbnails' ) בקובץ functions.php.

מחוץ ללולאה או לפי מזהה פוסט

כאשר אתם מחוץ ללולאה, למשל בווידג'ט או בהוק, העבירו את מזהה הפוסט כארגומנט הראשון:

$thumb_url = get_the_post_thumbnail_url( 42, 'full' );

אם אתם צריכים גם את מידות התמונה, קבלו קודם את מזהה הקובץ המצורף (attachment) והשתמשו ב-wp_get_attachment_image_src():

$thumb_id = get_post_thumbnail_id( 42 );
$image    = wp_get_attachment_image_src( $thumb_id, 'large' );

if ( $image ) {
    list( $url, $width, $height ) = $image;
}

אם אתם צריכים רק את הכתובת לפי מזהה הקובץ המצורף, wp_get_attachment_image_url( $thumb_id, 'large' ) היא הגרסה הקצרה יותר.

הקישור לתמונה הראשית דרך ה-REST API

אובייקט פוסט שמגיע מה-REST API כולל רק את featured_media, כלומר את מזהה הקובץ המצורף. הוסיפו _embed=wp:featuredmedia כדי לקבל את נתוני התמונה באותה בקשה:

fetch( '/wp-json/wp/v2/posts?_embed=wp:featuredmedia' )
    .then( ( response ) => response.json() )
    .then( ( posts ) => {
        posts.forEach( ( post ) => {
            const media = post._embedded?.[ 'wp:featuredmedia' ]?.[ 0 ];
            const url   = media?.source_url;                        // original image
            const large = media?.media_details?.sizes?.large?.source_url; // large size, if generated
            console.log( post.id, url, large );
        } );
    } );

הגבלת _embed לקשר (relation) אחד נתמכת מאז וורדפרס 5.4, כפי שמתואר בתיעוד REST API global parameters.

אם אתם משתמשים גם ב-_fields, כללו ברשימה את _links ואת _embedded, אחרת ה-embed לא יתבצע. לדוגמה מלאה, ראו את הפוסט הצגת פוסטים מבלוג אחר באתר שלכם באמצעות REST API.

שאלות נפוצות

שאלות נפוצות על קבלת הקישור לתמונה הראשית בוורדפרס: