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

تابع wp_enqueue_media() یکی از ابزارهای مهم در توسعه قالب‌ها و افزونه‌های وردپرس است که به شما اجازه می‌دهد تا کتابخانه مدیا و رابط آپلود فایل‌های وردپرس را در صفحات دلخواه بارگذاری کنید. این تابع در واقع مجموعه‌ اسکریپت‌ها، استایل‌ها و تنظیمات مربوط به مدیا مدال (Media Modal) را ثبت و در صف بارگذاری قرار می‌دهد تا بتوانید از ماژول‌های انتخاب فایل، پیش‌نمایش و آپلود در رابط کاربری خود استفاده کنید.

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

• زمانی که می‌خواهید یک Uploader یا Media Selector مشابه کتابخانه وردپرس در متاباکس‌ها، تنظیمات قالب یا صفحه اختصاصی ادمین داشته باشید.
• وقتی اسکریپت‌های فرانت‌اند شما نیاز به دسترسی به API جاوااسکریپت مدیا (wp.media) دارند.
• برای استفاده از کتابخانه فایل‌ها بدون بارگذاری مجدد صفحه و نمایش مدال انتخاب فایل.

نکات کلیدی درباره رفتار تابع

• تابع باید قبل از enqueue شدن اسکریپت‌هایی که به wp.media نیاز دارند فراخوانی شود.
• معمولاً در هوک admin_enqueue_scripts فراخوانی می‌شود مگر اینکه بخواهید در فرانت‌اند استفاده کنید.
• این تابع استایل‌ها، تصاویر بندانگشتی، و ماژول‌های مدیا را بارگذاری می‌کند و شامل کدهای JS مثل wp.media.view و wp.media.model است.

نمونه کاربرد رایج: اضافه کردن انتخابگر تصویر در متاباکس

// functions.php یا فایل افزونه
function myplugin_enqueue_media($hook) {
    // فقط در صفحه ویرایش پست لازم است
    if ( 'post.php' !== $hook && 'post-new.php' !== $hook ) {
        return;
    }
    wp_enqueue_media();
    wp_enqueue_script( 'myplugin-media', plugin_dir_url(__FILE__) . 'js/myplugin-media.js', array('jquery'), '1.0', true );
    wp_localize_script( 'myplugin-media', 'MyPluginMedia', array(
        'title' => __('انتخاب تصویر', 'text-domain'),
        'button' => __('انتخاب', 'text-domain'),
    ));
}
add_action( 'admin_enqueue_scripts', 'myplugin_enqueue_media' );

توضیح: در این کد ابتدا با چک کردن هوک صفحه، از اجرای اضافه در صفحات دیگر جلوگیری می‌کنیم. سپس wp_enqueue_media() را فراخوانی می‌کنیم تا کتابخانه مدیا بارگذاری شود و بعد اسکریپت اختصاصی خود را که به wp.media وابسته است enqueue می‌کنیم. wp_localize_script برای ارسال متون و تنظیمات به JS استفاده شده است.

کد JS برای باز کردن مدال و انتخاب تصویر

// js/myplugin-media.js
jQuery(document).ready(function($){
    var frame;
    $('#myplugin-select-image').on('click', function(e){
        e.preventDefault();
        if (frame) {
            frame.open();
            return;
        }
        frame = wp.media({
            title: MyPluginMedia.title,
            button: { text: MyPluginMedia.button },
            multiple: false
        });
        frame.on('select', function(){
            var attachment = frame.state().get('selection').first().toJSON();
            $('#myplugin-image-id').val(attachment.id);
            $('#myplugin-image-preview').attr('src', attachment.url).show();
        });
        frame.open();
    });
});

توضیح: این اسکریپت با استفاده از wp.media یک مدال باز می‌کند. اگر کاربر تصویری انتخاب کند، اطلاعات فایل (از جمله آیدی و آدرس url) گرفته شده و در فیلدهای مخفی و پیش‌نمایش درج می‌شود. بررسی وجود متغیر frame از باز شدن چندباره مدال جلوگیری می‌کند.

ذخیره مقدار و نکات امنیتی

function myplugin_save_post($post_id) {
    if ( defined('DOING_AUTOSAVE') && DOING_AUTOSAVE ) return;
    if ( ! current_user_can('edit_post', $post_id) ) return;
    if ( isset($_POST['myplugin_image_id']) ) {
        update_post_meta($post_id, '_myplugin_image_id', intval($_POST['myplugin_image_id']));
    } else {
        delete_post_meta($post_id, '_myplugin_image_id');
    }
}
add_action('save_post', 'myplugin_save_post');

توضیح: قبل از ذخیره داده‌ها، چک‌هایی برای جلوگیری از ذخیره خودکار یا دسترسی غیرمجاز انجام می‌شود. مقدار ورودی با intval پاک‌سازی شده و متا به روز می‌شود.

بهینه‌سازی و موارد پیشرفته

• اگر نیاز دارید مدیا در فرانت‌اند نیز کار کند، می‌توانید wp_enqueue_media() را در هوکی مناسب برای فرانت اند فراخوانی کنید، اما دقت کنید که بار اضافی اسکریپت‌ها روی سرعت صفحه تأثیر می‌گذارد.
• برای انتخاب چند فایل از گزینه multiple: true در ایجاد frame استفاده کنید و با حلقه آیتم‌ها را پردازش کنید.
• در صورت نیاز به بارگذاری سفارشی یا محدود کردن نوع فایل‌ها، از آرگومان‌های library یا mimeType در تنظیمات مدیا استفاده کنید.

جدول مقایسه سریع: admin vs frontend

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

تابع wp_enqueue_media() ابزار استاندارد و امنی برای بهره‌گیری از رابط مدیا وردپرس در پروژه‌های سفارشی است. همواره آن را قبل از enqueue اسکریپت‌های وابسته فراخوانی کنید، از چک‌های امنیتی هنگام ذخیره‌سازی دیتای کاربر استفاده نمایید و در صورت استفاده در فرانت‌اند به حجم و کارایی صفحه توجه کنید. با ترکیب صحیح PHP و JS می‌توانید تجربه کاربری مشابه پنل وردپرس را در بخش‌های سفارشی فراهم کنید.

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

ارسال