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

تابع get_custom_header() یکی از توابع مفید وردپرس برای دسترسی به اطلاعات هدر سفارشی (Custom Header) است. این تابع объект حاوی اطلاعات فعلی هدر را برمی‌گرداند که شامل آدرس تصویر، اندازه‌ها و شناسه پیوست (اگر موجود باشد) است. در این مقاله به صورت مرحله‌به‌مرحله کاربردها، نمونه‌های عملی، نکات امنیتی و بهینه‌سازی برای استفاده حرفه‌ای از این تابع می‌پردازیم.

چرا از get_custom_header() استفاده کنیم؟

• دسترسی مستقیم به تمام خصوصیات هدر (url، width، height، thumbnail_url، attachment_id).
• قابلیت ساخت خروجی‌های سفارشی (تصویر درون HTML، background-image، srcset برای ریسپانسیو).
• ترکیب با add_theme_support(‘custom-header’) برای کنترل کامل روی رفتار هدر در قالب.

خواص مهم شیء بازگشتی

نمونه ساده: نمایش تصویر هدر با get_custom_header()

<?php
$header = get_custom_header();

if ( $header && isset( $header->url ) ) {
    echo '<img src="'.esc_url( $header->url ).'" width="'.esc_attr( $header->width ).'" height="'.esc_attr( $header->height ).'" alt="Site Header">';
} else {
    echo '<!-- No custom header set -->';
}
?>

توضیح: این کد ابتدا شیء هدر را می‌گیرد و اگر خصوصیت url موجود باشد تصویری خروجی می‌دهد. از توابع esc_url و esc_attr برای امنیت و جلوگیری از تزریق استفاده شده است. اگر هدر تنظیم نشده باشد پیغام کامنتی نمایش داده می‌شود.

مثال بهتر: استفاده از شناسه پیوست برای srcset (ریسپانسیو)

<?php
$header = get_custom_header();

if ( $header && ! empty( $header->attachment_id ) ) {
    $src = wp_get_attachment_image_url( $header->attachment_id, 'full' );
    $srcset = wp_get_attachment_image_srcset( $header->attachment_id, 'full' );
    $sizes = '(max-width: 1200px) 100vw, 1200px';

    echo '<img src="'.esc_url( $src ).'" srcset="'.esc_attr( $srcset ).'" sizes="'.esc_attr( $sizes ).'" alt="Site Header">';
} elseif ( $header && ! empty( $header->url ) ) {
    echo '<img src="'.esc_url( $header->url ).'" alt="Site Header">';
}
?>

توضیح: در این نسخه اگر attachment_id موجود باشد از توابع wp_get_attachment_image_url و wp_get_attachment_image_srcset برای ساخت تصویر ریسپانسیو استفاده می‌کنیم. این باعث می‌شود مرورگر تصویر مناسب با اندازه صفحه بارگذاری کند و عملکرد و بار شبکه بهینه شود. اگر شناسه موجود نباشد از url ساده استفاده می‌کنیم.

ثبت پشتیبانی هدر سفارشی در functions.php

<?php
add_action( 'after_setup_theme', 'mytheme_custom_header_setup' );
function mytheme_custom_header_setup() {
    add_theme_support( 'custom-header', array(
        'default-image'      => get_template_directory_uri() . '/assets/images/default-header.jpg',
        'width'              => 1600,
        'height'             => 400,
        'flex-height'        => true,
        'flex-width'         => true,
        'header-text'        => false,
        'wp-head-callback'   => 'mytheme_header_style',
    ) );
}
?>

توضیح: این کد قابلیت هدر سفارشی را برای قالب فعال می‌کند و پارامترهای پیش‌فرض مانند ابعاد و مسیر تصویر پیش‌فرض را تعیین می‌کند. wp-head-callback به شما امکان می‌دهد استایل‌های سفارشی برای هدر هنگام بارگذاری در بخش front-end چاپ کنید.

نمونه تابع استایل هدر (wp-head-callback)

<?php
function mytheme_header_style() {
    $header = get_custom_header();
    if ( empty( $header ) ) {
        return;
    }
    $color = get_header_textcolor();
    ?>
    <style type="text/css">
        .site-header {
            background-image: url('<?php echo esc_url( $header->url ); ?>');
            background-size: cover;
            background-position: center;
        }
        
        .site-title, .site-description { position: absolute; clip: rect(1px, 1px, 1px, 1px); }
        
    </style>
    <?php
}
?>

توضیح: این کد CSS را در head قرار می‌دهد و تصویر هدر را به‌عنوان background برای المان با کلاس .site-header تنظیم می‌کند. همچنین در صورت خاموش بودن نمایش متن هدر، متن به‌صورت مخفی در می‌آید.

نکات و بهترین شیوه‌ها

• همیشه خروجی تصویر را با esc_url و مقادیر عددی با esc_attr امن کنید.
• برای عملکرد بهتر از srcset استفاده کنید تا مرورگر تصاویر مناسب را انتخاب کند.
• اگر هدر به عنوان background استفاده می‌شود از background-size: cover برای پوشش کامل بهره ببرید.
• در توسعه قالب، قابلیت flex-width و flex-height را اگر لازم دارید فعال کنید تا کاربر بتواند ابعاد دلخواه انتخاب کند.
• برای سازگاری با رتینا و نمایشگرهای با تراکم بالا، تصاویر بزرگ‌تر و srcset را در نظر بگیرید.

عیب‌یابی سریع

• اگر get_custom_header() مقدار null برمی‌گرداند: مطمئن شوید add_theme_support(‘custom-header’) در فایل functions.php اجرا شده و یک تصویر پیش‌فرض یا هدر آپلود شده وجود دارد.
• اگر attachment_id خالی است: ممکن است هدر از طریق آدرس مستقیم تنظیم شده باشد (نه از کتابخانه مدیا)، در این حالت روی url تکیه کنید.
• برای مطمئن شدن از دسترسی به خصوصیات، همیشه با isset یا empty بررسی کنید.

جمع‌بندی

تابع get_custom_header() یک ابزار قدرتمند برای دسترسی به اطلاعات هدر سفارشی در وردپرس است. با ترکیب آن با امکانات موجود در API مدیا و توابع مربوط به srcset می‌توان تجربه کاربری بهتر و لود سریع‌تر صفحه ایجاد کرد. رعایت نکات امنیتی و استفاده از توابع Escaping، کدنویسی ایمن و بهینه را تضمین خواهد کرد.

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

ارسال