آموزش تابع wp_get_attachment_image_src() در وردپرس و کاربرد آن

تابع wp_get_attachment_image_src() یکی از توابع پایه در وردپرس برای گرفتن آدرس تصویر پیوست (attachment) است. این تابع به شما آدرس (URL)، عرض، ارتفاع و اطلاعاتی دربارهٔ اینکه آیا تصویر یک نسخهٔ میانی (intermediate) است یا نه را برمی‌گرداند. در این مقاله به صورت کامل پارامترها، مقدار بازگشتی، مثال‌های عملی و نکات بهینه‌سازی را توضیح می‌دهیم.

امضا و پارامترها

• $attachment_id (int) — شناسهٔ پیوست (attachment ID) که معمولا از get_post_thumbnail_id() یا از metadata تصویر گرفته می‌شود.
• $size (string|array) — اندازهٔ تصویر که می‌تواند نام اندازه مثل ‘thumbnail’, ‘medium’, ‘full’ یا آرایه‌ای مثل array(300,200) باشد.
• $icon (bool) — اگر true باشد و فایل یک نوع غیرتصویری باشد، آیکون پیش‌فرض فایل بازگردانده می‌شود.

مقدار بازگشتی

تابع در صورت موفقیت یک آرایه برمی‌گرداند:

مثال پایه

$thumb = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), 'full' );
if ( $thumb ) {
    echo '<img src="' . esc_url( $thumb[0] ) . '" width="' . esc_attr( $thumb[1] ) . '" height="' . esc_attr( $thumb[2] ) . '" alt="' . esc_attr( get_the_title( $post->ID ) ) . '">';
}

در این مثال ابتدا شناسه تصویر شاخص را می‌گیریم، سپس با wp_get_attachment_image_src آدرس و ابعاد تصویر کامل را دریافت می‌کنیم. قبل از چاپ URL و مقادیر دیگر از توابع escaping مثل esc_url و esc_attr استفاده شده تا خروجی امن باشد.

مثال استفاده برای بک‌گراند در CSS

$bg = wp_get_attachment_image_src( $image_id, 'large' );
if ( $bg ) {
    echo 'style="background-image: url(' . esc_url( $bg[0] ) . ');"';
}

اگر بخواهید تصویری را به عنوان background استفاده کنید، فقط URL نیاز است. دقت کنید که برای ریسپانسیو بودن بهتر است از srcset یا تصاویر چند اندازه استفاده کنید (راهبرد در ادامه توضیح داده شده).

استفاده از اندازهٔ آرایه‌ای

$custom = wp_get_attachment_image_src( $image_id, array( 300, 200 ) );

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

چطور با srcset و sizes کار کنیم (تصاویر ریسپانسیو)

wp_get_attachment_image_src تنها یک URL می‌دهد و قادر به تولید srcset نیست. برای استفاده از تصاویر ریسپانسیو بهتر است از توابع مرتبط استفاده کنید:

$src = wp_get_attachment_image_src( $image_id, 'large' );
$srcset = wp_get_attachment_image_srcset( $image_id, 'large' );
$sizes = wp_get_attachment_image_sizes( $image_id, 'large' );

if ( $src ) {
    echo '<img src="' . esc_url( $src[0] ) . '" srcset="' . esc_attr( $srcset ) . '" sizes="' . esc_attr( $sizes ) . '" alt="">';
}

در این نمونه از wp_get_attachment_image_srcset و wp_get_attachment_image_sizes استفاده شده تا مرورگر بتواند بهترین تصویر را بر اساس عرض صفحه انتخاب کند. اگر هدف شما ریسپانسیو است، بهتر است از wp_get_attachment_image() استفاده کنید که تمام این атрибوت‌ها را خودکار اضافه می‌کند.

مثال بهتر: استفاده از wp_get_attachment_image()

echo wp_get_attachment_image( $image_id, 'large', false, array( 'class' => 'my-image-class', 'alt' => 'توضیح تصویر' ) );

این تابع یک تگ <img> کامل با srcset، sizes و attributes مشخص شده برمی‌گرداند. اگر به خروجی کامل نیاز دارید این گزینه امن‌تر و بهینه‌تر است چون WordPress خودش مدیریت srcset را انجام می‌دهد.

موارد و نکات کاربردی و خطاها

• اگر شناسهٔ پیوست اشتباه باشد، تابع مقدار false بازمی‌گرداند — همیشه مقدار بازگشتی را چک کنید.
• برای فایل‌های غیرتصویری (مانند PDF) با پارامتر $icon=true می‌توانید آیکون نوع فایل را دریافت کنید.
• در حلقه‌های بزرگ از فراخوانی‌های متعدد این تابع پرهیز کنید؛ برای نمایش فهرستی از پست‌ها بهتر است دادهٔ attachment را کش یا ابتدا درون آرایه جمع‌آوری کنید.
• همیشه خروجی‌های URL و attributeها را با esc_url و esc_attr امن کنید.

مثال بهینه‌شده برای حلقه‌ها

$posts = get_posts( array( 'posts_per_page' => 10 ) );
$image_data = array();

foreach ( $posts as $p ) {
    $id = get_post_thumbnail_id( $p->ID );
    if ( $id ) {
        $image_data[ $p->ID ] = wp_get_attachment_image_src( $id, 'medium' );
    }
}

// سپس در نمایش، فقط از آرایه خوانده می‌شود (یکبار فراخوانی انجام شده)
foreach ( $posts as $p ) {
    if ( ! empty( $image_data[ $p->ID ] ) ) {
        $img = $image_data[ $p->ID ];
        echo '<img src="' . esc_url( $img[0] ) . '" width="' . esc_attr( $img[1] ) . '" height="' . esc_attr( $img[2] ) . '" alt="' . esc_attr( get_the_title( $p ) ) . '">';
    }
}

در این الگو، فراخوانی wp_get_attachment_image_src فقط یکبار برای هر پست انجام می‌شود که کارایی را در لیست‌های طولانی بهبود می‌بخشد.

جمع‌بندی و توصیه‌های نهایی

• wp_get_attachment_image_src برای دسترسی سریع به URL و ابعاد تصویر مناسب است.
• برای خروجی HTML کامل و مدیریت srcset از wp_get_attachment_image استفاده کنید.
• در کاربردهای ریسپانسیو حتماً از wp_get_attachment_image_srcset و sizes بهره ببرید.
• همیشه خروجی‌ها را Escaping کنید و در حلقه‌ها عملکرد را با کش یا جمع‌آوری داده‌ها بهینه کنید.

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

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال