دریافت مستقیم URL تصویر شاخص در وردپرس

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

توی این آموزش، اول ساده‌ترین روش دریافت URL تصویر شاخص در وردپرس رو می‌بینید. بعد سراغ استفاده داخل و خارج از حلقه نوشته‌ها، انتخاب اندازه تصویر، کنترل نوشته‌های بدون تصویر شاخص و روش دو مرحله‌ای دریافت آدرس می‌ریم. در آخر هم خطاهای رایجی رو بررسی می‌کنیم که ممکنه باعث دریافت آدرس اشتباه یا خروجی خالی بشن.

ساده‌ترین روش دریافت URL تصویر شاخص در وردپرس

برای دریافت مستقیم آدرس تصویر شاخص، ساده‌ترین انتخاب تابع get_the_post_thumbnail_url() هست. تابع در وردپرس یعنی یک ابزار آماده که کار مشخصی رو انجام می‌ده. اگه با مفهوم تابع آشنا نیستید، راهنمای توابع پرکاربرد وردپرس شروع خوبی براتون هست.

تابع get_the_post_thumbnail_url() چه کاری انجام می‌ده؟

تابع get_the_post_thumbnail_url() شناسه نوشته و اندازه تصویر رو می‌گیره و آدرس مستقیم فایل تصویر شاخص رو برمی‌گردونه. اگه نوشته تصویر شاخص نداشته باشه، خروجی تابع false هست. یعنی به‌جای یک URL معتبر، مقدار «نادرست» برمی‌گرده و باید قبل از نمایش نتیجه اون رو بررسی کنید.

ساختار کلی تابع به این شکله:

<?phpget_the_post_thumbnail_url( $post_id, $size );?>

مقدار $post_id شناسه نوشته هست و $size اندازه تصویر رو مشخص می‌کنه. برای نمونه، می‌تونید از thumbnail، medium، large یا full استفاده کنید.

کد دریافت URL تصویر شاخص داخل حلقه نوشته‌ها

حلقه نوشته‌ها یا Loop بخشی از کد قالب هست که وردپرس توی اون نوشته‌ها رو یکی‌یکی می‌خونه و نمایش می‌ده. وقتی کد داخل حلقه باشه، تابع می‌تونه نوشته فعلی رو تشخیص بده. با این حال، بهتره شناسه نوشته رو به‌صورت واضح با get_the_ID() به تابع بدید:

<?php$thumbnail_url = get_the_post_thumbnail_url( get_the_ID(), 'large' );if ( $thumbnail_url ) {    echo esc_url( $thumbnail_url );}?>

تابع esc_url() آدرس رو قبل از چاپ برای استفاده توی HTML پاک‌سازی می‌کنه. اگه فقط برای یک کاربرد خاص به تگ ساده img نیاز دارید، می‌تونید از این نمونه کمک بگیرید:

<?php$thumbnail_id  = get_post_thumbnail_id( get_the_ID() );$thumbnail_url = get_the_post_thumbnail_url( get_the_ID(), 'large' );$thumbnail_alt = get_post_meta( $thumbnail_id, '_wp_attachment_image_alt', true );if ( $thumbnail_url ) :?>    <img src="<?php echo esc_url( $thumbnail_url ); ?>" alt="<?php echo esc_attr( $thumbnail_alt ); ?>"><?php endif; ?>

این نمونه متن جایگزین ثبت‌شده برای خود تصویر رو می‌خونه. بهتره متن جایگزین، کاربرد یا محتوای واقعی تصویر رو توضیح بده؛ پس عنوان نوشته همیشه جایگزین مناسبی برای اون نیست. اگه تصویر فقط تزئینیه، خالی‌بودن ویژگی alt می‌تونه انتخاب درستی باشه.

این کد فقط یک تگ تصویر ساده می‌سازه و ویژگی‌های واکنش‌گرا مثل srcset و sizes رو به‌صورت دستی اضافه نمی‌کنه. برای نمایش خود تصویر در بیشتر پروژه‌های قالب، استفاده از the_post_thumbnail() یا wp_get_attachment_image() انتخاب کامل‌تریه، چون وردپرس می‌تونه ویژگی‌های لازم تصویر رو مدیریت کنه. ولی وقتی فقط آدرس فایل رو لازم دارید، get_the_post_thumbnail_url() مستقیم‌تره.

چطور نبودن تصویر شاخص رو بررسی کنید؟

قبل از چاپ آدرس می‌تونید خود خروجی تابع رو بررسی کنید. روش دیگه استفاده از تابع has_post_thumbnail() هست. این تابع مشخص می‌کنه نوشته تصویر شاخص داره یا نه:

<?phpif ( has_post_thumbnail() ) {    $thumbnail_url = get_the_post_thumbnail_url( get_the_ID(), 'large' );    echo esc_url( $thumbnail_url );} else {    echo 'این نوشته تصویر شاخص نداره.';}?>

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

دریافت URL تصویر شاخص خارج از حلقه

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

گرفتن آدرس تصویر با شناسه نوشته

فرض کنید شناسه نوشته موردنظرتون 123 هست. برای گرفتن نسخه بزرگ تصویر شاخص می‌تونید این کد رو بنویسید:

<?php$post_id       = 123;$thumbnail_url = get_the_post_thumbnail_url( $post_id, 'large' );if ( $thumbnail_url ) {    echo esc_url( $thumbnail_url );}?>

عدد 123 فقط یک نمونه هست. باید اون رو با شناسه واقعی نوشته، برگه یا نوع نوشته سفارشی خودتون عوض کنید.

نمایش URL یا ذخیره اون در متغیر

تابع get_the_post_thumbnail_url() آدرس رو چاپ نمی‌کنه؛ اون رو برمی‌گردونه. به همین دلیل می‌تونید نتیجه رو داخل یک متغیر ذخیره کنید و بعد هرجا لازم بود ازش کمک بگیرید:

<?php$thumbnail_url = get_the_post_thumbnail_url( 123, 'full' );if ( $thumbnail_url ) {    // استفاده از آدرس در کدهای بعدی}?>

اگه فقط می‌خواید آدرس رو توی صفحه نمایش بدید، از echo esc_url( $thumbnail_url ); استفاده کنید. اگه قراره URL وارد پردازش دیگه‌ای بشه، لازم نیست همون لحظه اون رو چاپ کنید.

انتخاب اندازه تصویر شاخص

وردپرس موقع آپلود تصویر، چند نسخه با ابعاد مختلف می‌سازه. انتخاب نسخه مناسب کمک می‌کنه تصویر خیلی بزرگ رو برای یک فضای کوچک بارگذاری نکنید. این کار می‌تونه حجم دانلود صفحه رو کمتر کنه و به افزایش سرعت سایت وردپرس کمک کنه.

اندازه‌های thumbnail، medium، large و full چه فرقی دارن؟

• thumbnail: نسخه بندانگشتی و کوچک تصویر هست. ابعاد دقیق اون به تنظیمات رسانه سایتتون بستگی داره.
• medium: نسخه متوسط تصویر هست و برای بخش‌هایی با فضای محدود کاربرد داره.
• large: نسخه بزرگ تصویر هست و معمولاً برای محتوای اصلی یا کارت‌های عریض به کار میاد.
• full: فایل اصلی آپلودشده رو برمی‌گردونه. این نسخه ممکنه حجم و ابعاد زیادی داشته باشه.

ابعاد thumbnail، medium و large رو می‌تونید از بخش «تنظیمات ← رسانه» در پیشخوان وردپرس ببینید. قالب یا افزونه‌ها هم ممکنه اندازه‌های دیگه‌ای به سایت اضافه کنن.

چطور یک اندازه دلخواه رو انتخاب کنید؟

کافیه نام اندازه رو به‌عنوان آرگومان دوم تابع بنویسید. برای نمونه، کد زیر URL نسخه متوسط رو می‌گیره:

<?php$thumbnail_url = get_the_post_thumbnail_url( get_the_ID(), 'medium' );?>

می‌تونید یک آرایه شامل عرض و ارتفاع هم به تابع بدید. ولی این آرایه فایل تازه‌ای با همون ابعاد نمی‌سازه و نتیجه به نسخه‌هایی بستگی داره که وردپرس از قبل برای تصویر ساخته. اگه فایل دقیق ۸۰۰ در ۴۵۰ پیکسل لازم دارید، بهتره یک اندازه سفارشی با همین ابعاد ثبت کنید:

<?php$thumbnail_url = get_the_post_thumbnail_url( get_the_ID(), array( 800, 450 ) );?>

استفاده از اندازه سفارشی و بازسازی تصاویر قدیمی

اگه قالب اختصاصی دارید، می‌تونید با تابع add_image_size() یک اندازه سفارشی ثبت کنید. بهتره این کد داخل فایل functions.php قالب یا محل مناسب راه‌اندازی قالب قرار بگیره:

<?phpadd_action( 'after_setup_theme', function () {    add_image_size( 'article-card', 800, 450, true );} );?>

مقدار true یعنی وردپرس تصویر رو برش می‌ده تا به ابعاد تعیین‌شده برسه. بعد از ثبت اندازه، می‌تونید URL اون رو با نام article-card بگیرید:

<?php$thumbnail_url = get_the_post_thumbnail_url( get_the_ID(), 'article-card' );?>

اندازه تازه فقط برای تصویرهایی ساخته می‌شه که بعد از ثبت اون آپلود می‌کنید. برای رسانه‌های قدیمی باید نسخه‌های تصویر رو دوباره بسازید. اگه به خط فرمان سرور دسترسی دارید، دستور رسمی WP-CLI برای بازسازی رسانه‌ها این کار رو انجام می‌ده:

wp media regenerate --yes

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

روش دریافت URL با شناسه فایل تصویر

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

دریافت شناسه با get_post_thumbnail_id()

تابع get_post_thumbnail_id() شناسه فایل رسانه‌ای رو برمی‌گردونه که به‌عنوان تصویر شاخص نوشته انتخاب شده:

<?php$thumbnail_id = get_post_thumbnail_id( get_the_ID() );?>

اگه نوشته تصویر شاخص نداشته باشه، معمولاً مقدار 0 برمی‌گرده. اگه خود نوشته معتبر نباشه، نتیجه می‌تونه false باشه. پس قبل از رفتن به مرحله بعد، شناسه رو بررسی کنید.

دریافت آدرس با wp_get_attachment_image_src()

تابع wp_get_attachment_image_src() اطلاعات نسخه درخواستی تصویر رو به‌شکل یک آرایه برمی‌گردونه. این آرایه URL، عرض، ارتفاع و وضعیت تغییر اندازه تصویر رو شامل می‌شه:

<?php$thumbnail_id = get_post_thumbnail_id( get_the_ID() );if ( $thumbnail_id ) {    $thumbnail_data = wp_get_attachment_image_src( $thumbnail_id, 'large', false );    if ( $thumbnail_data ) {        $thumbnail_url    = $thumbnail_data[0];        $thumbnail_width  = $thumbnail_data[1];        $thumbnail_height = $thumbnail_data[2];        echo esc_url( $thumbnail_url );    }}?>

آرگومان سوم رو false گذاشتیم، چون برای تصویر شاخص به آیکن نوع فایل نیاز نداریم. قبل از خواندن خانه‌های آرایه هم نتیجه رو بررسی کردیم تا اگه تابع false برگردوند، خطای PHP نگیرید.

چه زمانی این روش دو مرحله‌ای به کارتون میاد؟

اگه فقط آدرس تصویر رو می‌خواید، همون get_the_post_thumbnail_url() ساده‌تره. روش دو مرحله‌ای وقتی به کارتون میاد که علاوه بر URL، عرض و ارتفاع تصویر رو هم لازم دارید یا می‌خواید با شناسه فایل رسانه کار دیگه‌ای انجام بدید.

برای نمونه، شاید بخواید اطلاعات تکمیلی فایل، متن جایگزین یا متادیتای رسانه رو بخونید. داشتن شناسه پیوست توی چنین شرایطی دستتون رو بازتر می‌ذاره.

پیش‌نیازهای نمایش تصویر شاخص در قالب

وجود توابع دریافت URL به این معنی نیست که هر قالبی حتماً بخش انتخاب تصویر شاخص رو فعال کرده. قالب باید پشتیبانی از قابلیت post-thumbnails رو اعلام کنه.

بررسی پشتیبانی قالب از post-thumbnails

برای بررسی پشتیبانی قالب می‌تونید از تابع current_theme_supports() کمک بگیرید:

<?phpif ( current_theme_supports( 'post-thumbnails' ) ) {    // قالب از تصویر شاخص پشتیبانی می‌کنه.}?>

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

اگه با یک نوع نوشته سفارشی کار می‌کنید، خود اون نوع نوشته هم باید از قابلیت thumbnail پشتیبانی کنه. موقع ثبت نوع نوشته می‌تونید این قابلیت رو داخل بخش supports قرار بدید:

<?phpregister_post_type( 'book', array(    'supports' => array( 'title', 'editor', 'thumbnail' ),) );?>

این کد فقط بخش مرتبط با پشتیبانی قابلیت‌ها رو نشون می‌ده و نمونه کامل ثبت نوع نوشته نیست. اگه نوع نوشته قبلاً ثبت شده، باید تنظیمات همون کد یا افزونه سازنده اون رو بررسی کنید.

فعال‌کردن تصویر شاخص در قالب اختصاصی

اگه قالب اختصاصی می‌سازید، پشتیبانی از تصویر شاخص رو با add_theme_support() فعال کنید. این کد باید در رویداد after_setup_theme اجرا بشه:

<?phpfunction mihanwp_theme_setup() {    add_theme_support( 'post-thumbnails' );}add_action( 'after_setup_theme', 'mihanwp_theme_setup' );?>

این کد معمولاً داخل فایل functions.php قالب قرار می‌گیره. اگه از قالب آماده استفاده می‌کنید، فایل‌های قالب اصلی رو مستقیم تغییر ندید؛ چون با به‌روزرسانی قالب ممکنه تغییراتتون از بین بره. برای تغییرات اختصاصی بهتره از چایلد تم یا افزونه اختصاصی سایتتون کمک بگیرید.

خطاهای رایج موقع دریافت URL تصویر شاخص

• استفاده از نام اندازه‌ای که ثبت نشده: اگه نامی مثل article-card رو به تابع بدید ولی اون اندازه قبلاً ثبت نشده باشه، نتیجه ممکنه چیزی نباشه که انتظار دارید. نام اندازه‌های موجود رو بررسی کنید یا اندازه سفارشی رو با add_image_size() بسازید.
• چاپ خروجی بدون بررسی مقدار false: توابع تصویر ممکنه وقتی فایل مناسبی پیدا نمی‌کنن، false برگردونن. همیشه قبل از چاپ URL یا خواندن آرایه، نتیجه رو بررسی کنید.
• استفاده از کد مخصوص حلقه در جای اشتباه: بیرون از حلقه، شناسه نوشته رو به تابع بدید. تکیه به نوشته فعلی در بخش‌هایی مثل ابزارک، درخواست سفارشی یا کدهای پس‌زمینه می‌تونه نتیجه اشتباهی بسازه.
• نداشتن تصویر شاخص برای نوشته: اگه برای نوشته تصویری انتخاب نکرده باشید، تابع URL معتبری تحویل نمی‌ده. با has_post_thumbnail() یا بررسی مستقیم خروجی، این وضعیت رو مدیریت کنید.
• فعال‌نبودن تصویر شاخص برای نوع نوشته سفارشی: پشتیبانی قالب به‌تنهایی کافی نیست. نوع نوشته سفارشی هم باید قابلیت thumbnail رو داخل تنظیمات supports داشته باشه.
• بازسازی‌نکردن اندازه‌های سفارشی برای تصاویر قدیمی: ثبت یک اندازه تازه، نسخه مربوط به فایل‌های قبلی رو خودکار نمی‌سازه. بعد از گرفتن نسخه پشتیبان، تصاویر قدیمی رو با ابزار مناسب بازسازی کنید.

سوالات متداول

جمع‌بندی

برای بیشتر پروژه‌ها، بهترین و ساده‌ترین روش دریافت URL تصویر شاخص در وردپرس استفاده از get_the_post_thumbnail_url() هست. داخل حلقه می‌تونید شناسه رو با get_the_ID() بگیرید و بیرون از حلقه باید شناسه نوشته موردنظرتون رو مشخص کنید. یادتون نره قبل از چاپ آدرس، خروجی تابع رو بررسی و URL رو با esc_url() پاک‌سازی کنید.

اگه علاوه بر URL به شناسه فایل، عرض یا ارتفاع تصویر نیاز دارید، روش دو مرحله‌ای get_post_thumbnail_id() و wp_get_attachment_image_src() انتخاب مناسب‌تریه. اندازه تصویر رو هم متناسب با محل نمایش انتخاب کنید تا فایل بزرگ و سنگین بی‌دلیل برای کاربر بارگذاری نشه. شاد و سربلند باشید. 🙂

تیم تولید محتوا

ما در تیم تولید محتوای میهن وردپرس در تلاش هستیم تا بهترین مقالات آموزشی در زمینه وردپرس و کسب‌و‌کارهای اینترنتی را تهیه کنیم. صحت محتوای این صفحه توسط رضا راد بررسی خواهد شد.