تصویر شاخص، یکی از پرکاربردترین ویژگی‌های وردپرس در قالب‌های مدرن است. این تصویر، در فهرست‌ها، شبکه‌های اجتماعی، نتایج جستجو، و گاه به‌عنوان عنصر LCP صفحه نقش کلیدی ایفا می‌کند. با اینکه فیلد تصویر شاخص، از وردپرس ۲.۹ به هسته اضافه شده، توابع اختصاصی آن همچنان کمتر از حدِ لازم شناخته شده‌اند. تسلط بر این توابع، تفاوت بین قالب کارت‌محورِ تمیز و قالب پر از کد خام را می‌سازد. این مقاله، توابع تصویر شاخص وردپرس را در ده گروه مرور می‌کند؛ از بررسی و نمایش تا اندازه‌ها، متادیتا، و کوئری بر اساس وجود تصویر. اگر با مفاهیم پایه آشنا نیستید، توابع وردپرس چیست، توابع دادهٔ نوشته، و سئوی تصویر را پیش از ادامه ببینید.

فعال‌سازی پشتیبانی از تصویر شاخص

پیش از هر کار، قالب باید پشتیبانی از تصویر شاخص را فعال کند. در فایل functions.php:

add_action( 'after_setup_theme', function() {
    add_theme_support( 'post-thumbnails' );

    // فعال‌سازی برای انواع‌نوشتهٔ خاص
    add_theme_support( 'post-thumbnails', array( 'post', 'page', 'project' ) );
} );

نکته‌ها: یک — هوک after_setup_theme: نه init، چون باید پیش از همهٔ تنظیمات بار شود. دو — انواع‌نوشته: اگر پارامتری ندهید، برای همهٔ انواع فعال می‌شود؛ اگر آرایه بدهید، فقط برای آن‌ها. سه — بازبینی قالب‌های قدیمی: بعضی قالب‌های آماده، این قابلیت را فعال کرده‌اند؛ در این حالت، خط را تکرار نکنید. راهنمای کامل هوک‌ها در هوک‌های وردپرس و نحوهٔ استفاده از add_action.

تصویر شاخص، بدون فعال‌سازی پشتیبانی در قالب، در پیشخوان ظاهر نمی‌شود؛ نیمی از «تصویر شاخص کار نمی‌کند»ها ریشه در همین خط ساده دارند.

بررسی وجود تصویر

پیش از هر نمایشی، وجود تصویر را بررسی کنید:

has_post_thumbnail( $post_id );              // بولی
get_post_thumbnail_id( $post_id );            // شناسهٔ رسانه یا 0 (یا false)

الگوی امن:

$thumb_id = get_post_thumbnail_id( get_the_ID() );
if ( $thumb_id ) {
    // تصویر وجود دارد
} else {
    // تصویر جایگزین
}

سه نکته: یک — has_post_thumbnail در حلقه: بدون پارامتر، نوشتهٔ جاری را بررسی می‌کند. دو — مقدار بازگشتی: get_post_thumbnail_id در نبود تصویر، رشتهٔ خالی یا false برمی‌گرداند؛ با if ( $id ) بررسی کنید. سه — در کارت‌ها و آرشیو: همیشه پیش از نمایش، وجود تصویر را چک کنید و برای نبود آن، جایگزین تعریف کنید. راهنمای تکمیلی در توابع دادهٔ نوشته.

نمایش تصویر شاخص

تابع اصلی نمایش، the_post_thumbnail است:

the_post_thumbnail();                                      // اندازهٔ پیش‌فرض
the_post_thumbnail( 'medium' );                             // اندازهٔ مشخص
the_post_thumbnail( 'large', array( 'class' => 'hero' ) );    // با کلاس
the_post_thumbnail( array( 400, 300 ) );                    // ابعاد دلخواه
the_post_thumbnail( 'medium', array( 'loading' => 'lazy' ) ); // با lazy-load

پارامترها: یک — اندازه: می‌تواند نام رجیستر‌شده (thumbnail، medium، large، full، post-thumbnail) باشد، آرایهٔ ابعاد array( width, height )، یا رشتهٔ ابعاد 400x300. دو — ویژگی‌ها: آرایه‌ای از attributeهای HTML روی تگ <img>. الگوی حرفه‌ای نمایش:

if ( has_post_thumbnail() ) {
    the_post_thumbnail( 'medium_large', array(
        'class'   => 'post-thumbnail-img',
        'loading' => 'lazy',
        'alt'     => esc_attr( get_the_title() ),
    ) );
} else {
    printf(
        '<img src="%s" alt="" class="post-thumbnail-placeholder" loading="lazy" />',
        esc_url( get_template_directory_uri() . '/assets/images/placeholder.webp' )
    );
}

نکته: the_post_thumbnail به‌طور خودکار کلاس attachment-{size} و wp-post-image را اضافه می‌کند. راهنمای کامل قالب در ساختار فایل‌های قالب استاندارد.

دریافت URL و مسیر

اگر فقط URL یا مسیر فایل لازم است، از توابع اختصاصی استفاده کنید:

get_the_post_thumbnail_url( $post_id, 'medium' );
get_the_post_thumbnail_url( null, 'large' );

// مسیر فایل روی سرور (کمتر کاربرد)
get_attached_file( $thumb_id );

الگوی کاربردی:

$thumb_url = get_the_post_thumbnail_url( get_the_ID(), 'large' );
if ( $thumb_url ) {
    printf(
        '<meta property="og:image" content="%s" />',
        esc_url( $thumb_url )
    );
}

نکته: get_the_post_thumbnail_url در نبود تصویر، false برمی‌گرداند. برای Open Graph و Twitter Card، وجود تصویر را چک کنید. راهنمای تکمیلی در توابع لینک و URL.

اندازه‌های تصویر

وردپرس چند اندازهٔ پیش‌فرض دارد و می‌توانید اندازهٔ اختصاصی اضافه کنید:

// اندازه‌های پیش‌فرض
// thumbnail   150x150 (cropped)
// medium      300x300 (max)
// medium_large 768x0
// large       1024x1024 (max)
// full        ابعاد اصلی

// افزودن اندازهٔ اختصاصی
add_action( 'after_setup_theme', function() {
    add_image_size( 'card-thumb', 400, 260, true );        // برش دقیق
    add_image_size( 'hero-image', 1600, 800, true );
    add_image_size( 'square-thumb', 300, 300, true );
} );

// نمایش
the_post_thumbnail( 'card-thumb' );

نکته‌ها: یک — پارامتر چهارم (true): برش دقیق (crop). بدون آن، تصویر با حفظ نسبت در حداکثر ابعاد ذخیره می‌شود. دو — تولید مجدد: پس از افزودن اندازهٔ جدید، تصاویر قبلی باید بازسازی شوند. افزونه‌هایی مثل Regenerate Thumbnails این کار را انجام می‌دهند. سه — نام‌گذاری: از نام‌های معنادار با پیشوند استفاده کنید تا با اندازه‌های قالب یا افزونهٔ دیگر تعارض نکنند. راهنمای انتخاب اندازه در فرمت تصویر مناسب وب و فشرده‌سازی تصاویر.

متادیتای تصویر

تصویر شاخص، از طریق توابع متادیتای پیوست، اطلاعات غنی در اختیار می‌گذارد:

$thumb_id = get_post_thumbnail_id( get_the_ID() );

// URL و اطلاعات فایل
$url      = wp_get_attachment_image_url( $thumb_id, 'large' );
$srcset   = wp_get_attachment_image_srcset( $thumb_id, 'large' );
$sizes    = wp_get_attachment_image_sizes( $thumb_id, 'large' );
$metadata = wp_get_attachment_metadata( $thumb_id );
$alt      = get_post_meta( $thumb_id, '_wp_attachment_image_alt', true );
$caption  = wp_get_attachment_caption( $thumb_id );

// ابعاد و اندازهٔ فایل
$file = get_attached_file( $thumb_id );
$size = $file ? filesize( $file ) : 0;

نمایش امن:

$thumb_id = get_post_thumbnail_id( get_the_ID() );
if ( $thumb_id ) {
    $alt = get_post_meta( $thumb_id, '_wp_attachment_image_alt', true );
    printf(
        '<img src="%s" alt="%s" class="thumb" />',
        esc_url( wp_get_attachment_image_url( $thumb_id, 'medium' ) ),
        esc_attr( $alt )
    );
}

راهنمای کامل متادیتای پیوست در توابع مدیریت رسانه و توابع متادیتا.

alt و ویژگی‌های اضافه

متن جایگزین تصویر، برای سئو و دسترس‌پذیری مهم است. سه الگو: یک — alt از متادیتای تصویر:

$thumb_id = get_post_thumbnail_id( get_the_ID() );
$alt = get_post_meta( $thumb_id, '_wp_attachment_image_alt', true );

printf(
    '<img src="%s" alt="%s" />',
    esc_url( wp_get_attachment_image_url( $thumb_id, 'medium' ) ),
    esc_attr( $alt )
);

دو — alt از عنوان نوشته: اگر متادیتای alt خالی است، از عنوان استفاده کنید:

$alt = $alt ? $alt : get_the_title();

سه — alt خالی برای تصاویر تزئینی: اگر تصویر فقط تزئینی است، alt="" بگذارید تا screen reader نادیده بگیرد. سه تذکر: یک — alt تکراری در همهٔ تصاویر، امتیاز سئو نمی‌سازد؛ توصیف واقعی لازم است. دو — از عنوان نوشته به‌عنوان alt همیشه مناسب نیست؛ چون alt باید توصیفِ تصویر باشد نه عنوانِ نوشته. سه — esc_attr برای alt الزامی است. راهنمای کامل در نقش alt در سئو، سئوی تصویر، و WCAG و دسترس‌پذیری.

ریسپانسیو و srcset

وردپرس از نسخهٔ ۴.۴ به بعد، srcset و sizes را به‌طور خودکار به the_post_thumbnail و wp_get_attachment_image اضافه می‌کند. الگوی سفارشی با کنترل کامل:

$thumb_id = get_post_thumbnail_id( get_the_ID() );
if ( $thumb_id ) {
    echo wp_get_attachment_image(
        $thumb_id,
        'large',
        false,
        array(
            'class'         => 'card-image',
            'loading'       => 'lazy',
            'fetchpriority' => 'auto',
        )
    );
}

مزیت wp_get_attachment_image نسبت به the_post_thumbnail: کنترل کامل روی اندازه، ویژگی‌ها، و بازگشت به‌صورت رشته. برای LCP، تصویر شاخصِ بالای صفحه را با loading => 'eager' و fetchpriority => 'high' بارگذاری کنید. راهنمای LCP در Core Web Vitals، بهینه‌سازی LCP، و چرا قالب‌ها کند می‌کنند.

تصویر شاخص، در صفحاتِ کارت‌محور، اولین چیزی است که کاربر می‌بیند و آخرین چیزی که در ذهنش می‌ماند؛ سرمایه‌گذاری روی درست نمایش‌دادنش، در نرخ‌کلیک بازمی‌گردد.

کوئری بر اساس تصویر شاخص

فیلتر نوشته‌ها بر اساس وجود یا نبود تصویر شاخص، با meta_query انجام می‌شود. دلیل: تصویر شاخص، در واقع متادیتایی با کلید _thumbnail_id است.

// نوشته‌هایی که تصویر شاخص دارند
$args = array(
    'post_type'      => 'post',
    'posts_per_page' => 12,
    'meta_query'     => array(
        array(
            'key'     => '_thumbnail_id',
            'compare' => 'EXISTS',
        ),
    ),
);

// نوشته‌هایی که تصویر شاخص ندارند
$args = array(
    'post_type'  => 'post',
    'meta_query' => array(
        array(
            'key'     => '_thumbnail_id',
            'compare' => 'NOT EXISTS',
        ),
    ),
);

نکته‌ها: یک — EXISTS در برابر ='1': EXISTS بسیار سریع‌تر است. دو — کوئری سنگین: در سایت‌های با نوشتهٔ زیاد، این کوئری ممکن است کند باشد؛ در این حالت، از cache نتایج استفاده کنید. سه — فیلتر بر اساس اندازهٔ تصویر: امکان‌پذیر نیست، چون اندازه در متادیتای تصویر ذخیره می‌شود نه در کلید. راهنمای بهینه‌سازی در بهینه‌سازی کوئری‌ها و کوئری سفارشی.

الگوهای ترکیبی در قالب

سه الگوی پرکاربرد در قالب‌های حرفه‌ای: یک — کارت نوشته با تصویر شاخص و جایگزین:

$thumb_id  = get_post_thumbnail_id( get_the_ID() );
$thumb_alt = $thumb_id ? get_post_meta( $thumb_id, '_wp_attachment_image_alt', true ) : '';

if ( $thumb_id ) {
    echo '<a href="' . esc_url( get_permalink() ) . '" class="card-link">';
    echo wp_get_attachment_image( $thumb_id, 'card-thumb', false, array(
        'class'   => 'card-image',
        'alt'     => esc_attr( $thumb_alt ?: get_the_title() ),
        'loading' => 'lazy',
    ) );
    echo '</a>';
} else {
    printf(
        '<a href="%s" class="card-link">
            <img src="%s" class="card-image card-placeholder" alt="" loading="lazy" />
        </a>',
        esc_url( get_permalink() ),
        esc_url( get_template_directory_uri() . '/assets/images/placeholder.webp' )
    );
}

دو — قهرمان صفحهٔ تک‌نوشته (Hero image):

$thumb_id = get_post_thumbnail_id( get_the_ID() );
if ( $thumb_id ) {
    echo '<div class="post-hero">';
    echo wp_get_attachment_image( $thumb_id, 'hero-image', false, array(
        'class'         => 'hero-img',
        'loading'       => 'eager',
        'fetchpriority' => 'high',
        'decoding'      => 'async',
    ) );
    echo '</div>';
}

سه — Open Graph برای شبکه‌های اجتماعی:

add_action( 'wp_head', function() {
    if ( ! is_singular() ) return;

    $thumb_id = get_post_thumbnail_id( get_the_ID() );
    if ( ! $thumb_id ) return;

    $url = wp_get_attachment_image_url( $thumb_id, 'large' );
    if ( ! $url ) return;

    printf( '<meta property="og:image" content="%s" />', esc_url( $url ) );
    printf( '<meta name="twitter:image" content="%s" />', esc_url( $url ) );
} );

این سه الگو، در قالب‌های حرفه‌ای به‌طور مکرر به‌کار می‌روند. راهنمای تکمیلی در ساختار فایل‌های قالب استاندارد، توسعهٔ قالب از صفر، و توابع دادهٔ نوشته.

بهینه‌سازی و سرعت

تصویر شاخص، در بسیاری از سایت‌ها بزرگ‌ترین فایل صفحه است. پنج تکنیک بهینه‌سازی: یک — اندازهٔ درست: برای کارت‌های فهرست، اندازه‌های بزرگ (مثلاً large = ۱۰۲۴) بارگذاری نکنید. یک اندازهٔ card-thumb با ابعاد واقعی نمایش تعریف کنید. دو — فرمت مدرن: WebP یا AVIF برای همهٔ تصاویر شاخص. راهنما در فرمت تصویر وب و WebP و JPEG. سه — lazy-load برای تصاویر زیر خط دید: loading="lazy" برای کارت‌ها و loading="eager" برای هیرو. چهار — srcset: با add_image_size و wp_get_attachment_image، وردپرس خودکار srcset می‌سازد. پنج — CDN تصویر: اگر حجم تصاویر زیاد است، سرویس‌هایی مثل Cloudflare Images یا Bunny Optimizer تفاوت محسوسی می‌سازند. راهنمای کامل در افزونه‌های بهینه‌سازی تصویر، فشرده‌سازی تصاویر، نقش CDN در سرعت، و بهینه‌سازی کد وردپرس. یک نکته: تصویر شاخص در کارت‌ها اگر در خط دید اول نباشد، lazy-load به‌طور محسوس سرعت اولیه را بهبود می‌دهد؛ ولی در LCPِ صفحهٔ تک‌نوشته، همان تصویر شاخص هیرو باید eager باشد.

اشتباهات رایج

توابع تصویر شاخص وردپرس، در ده گروه مرور شدند: فعال‌سازی، بررسی، نمایش، URL، اندازه‌ها، متادیتا، alt، srcset، کوئری، و بهینه‌سازی. تسلط بر این فهرست، در قالب‌های کارت‌محور مدرن، تفاوت بین طراحی حرفه‌ای و طراحی آماتور را می‌سازد. اگر امروز یک کار در این مسیر انجام می‌دهید: در یکی از فایل‌های قالب فعلی خود، به اندازهٔ تصویری که در کارت‌ها بار می‌شود نگاه کنید؛ اگر اندازه بزرگ‌تر از نمایش واقعی است، یک اندازهٔ اختصاصی تعریف کنید و تصاویر را بازسازی کنید. همان تغییر کوچک، سرعت صفحه را محسوس بهبود می‌دهد. اگر تجربه‌ای از یک باگ در نمایش یا بهینه‌سازی تصویر شاخص دارید، در دیدگاه‌ها بنویسید؛ همان گزارش‌های واقعی، این راهنما را برای توسعه‌دهندهٔ بعدی دقیق‌تر می‌کند. 🖼️