آموزش وردپرس | بلاگ وب‌داده

حل مشکل کار نکردن jQuery در قالب وردپرس

وقتی منوها باز نمی‌شوند، اسلایدر تکان نمی‌خورد یا کنسول خطای «jQuery is not defined» می‌دهد، معمولاً پای تداخل یا بارگذاری نادرست jQuery در میان است. در این راهنما گام‌به‌گام آن را رفع می‌کنیم.
حل مشکل کار نکردن jQuery در قالب وردپرس، یکی از رایج‌ترین دردسرهایی است که ممکن است بعد از نصب یک افزونه، به‌روزرسانی وردپرس یا فعال‌کردن یک قالب جدید با آن روبه‌رو شوید. نشانه‌اش هم مشخص است: بخش‌های تعاملی سایت مثل منوی موبایل، اسلایدر، پاپ‌آپ یا آکاردئون از کار می‌افتند و کنسول مرورگر خطاهایی مثل «jQuery is not defined» یا «$ is not a function» نشان می‌دهد. خبر خوب اینکه در بیشتر موارد ریشهٔ مشکل چند علت مشخص است و بدون دانش برنامه‌نویسی سنگین هم قابل حل است. در ادامه ابتدا علت را روشن می‌کنیم و بعد قدم‌به‌قدم سراغ رفع آن می‌رویم.
  • شایع‌ترین علت: استفاده از میان‌بر $ در حالی که وردپرس jQuery را در حالت no-conflict لود می‌کند.
  • تداخل نسخه‌ها: قالب یا افزونه نسخهٔ جداگانه‌ای از jQuery را لود می‌کند و با نسخهٔ هستهٔ وردپرس تداخل می‌کند.
  • ترتیب بارگذاری: افزونهٔ سرعت با defer/async باعث می‌شود jQuery بعد از اسکریپت‌های وابسته لود شود.
  • کد قدیمی: قالب/افزونهٔ قدیمی از توابع منسوخ‌شدهٔ jQuery استفاده می‌کند که در نسخهٔ 3.x حذف شده‌اند.
  • راهکار امن: ابتدا کنسول را بخوانید، سپس no-conflict و enqueue درست را اصلاح کنید و در نهایت تداخل افزونه/قالب را پیدا کنید.

در یک جمله

اگر بخش‌های جاوااسکریپتی سایت‌تان کار نمی‌کنند و کنسول خطای jQuery می‌دهد، در ۹۰٪ موارد کافی است کد را از $(document).ready به فرم no-conflict یعنی jQuery(document).ready(function($){ ... }) تغییر دهید و مطمئن شوید jQuery به‌درستی enqueue شده است؛ بقیهٔ موارد به تداخل افزونه یا افزونهٔ سرعت برمی‌گردد.
احتمالاً این مقاله را باز کرده‌اید چون یک بخش از سایت‌تان ناگهان از کار افتاده و دنبال راه‌حل فوری هستید. نگران نباشید و عجولانه تصمیم نگیرید؛ در ادامه بدون اصطلاحات پیچیده، از ساده‌ترین بررسی تا روش‌های کدنویسی، همه‌چیز را طوری توضیح می‌دهیم که خودتان بتوانید مشکل را پیدا و رفع کنید.

حل مشکل کار نکردن jQuery در قالب وردپرس چیست و چرا رخ می‌دهد؟

jQuery یک کتابخانهٔ جاوااسکریپت است که سال‌هاست بخش زیادی از افکت‌ها و بخش‌های تعاملی قالب‌ها و افزونه‌های وردپرس را اجرا می‌کند؛ از منوی کشویی و اسلایدر گرفته تا فرم‌ها و پاپ‌آپ‌ها. «کار نکردن jQuery» یعنی مرورگر نمی‌تواند دستورهای مبتنی بر این کتابخانه را اجرا کند، پس هر چیزی که به آن وابسته است متوقف می‌شود.
برای درک ریشهٔ ماجرا یک تشبیه ساده کمک می‌کند: jQuery مثل یک مترجم مشترک در یک ساختمان است. وردپرس این مترجم را یک‌بار برای همه استخدام می‌کند و از او می‌خواهد فقط با نام کاملش یعنی jQuery صدا زده شود، نه با لقب کوتاه $ (این همان حالت no-conflict است تا با کتابخانه‌های دیگر قاطی نشود). حالا اگر یک قالب یا افزونه بدون توجه به این قانون، مترجم را با لقب کوتاه صدا بزند یا مترجم دومی استخدام کند، سوءتفاهم پیش می‌آید و کدها اجرا نمی‌شوند.

نکتهٔ کلیدی

وردپرس jQuery را همراه هسته دارد و آن را در حالت no-conflict بارگذاری می‌کند. به همین دلیل در وردپرس نباید از $(document).ready استفاده کنید؛ چون میان‌بر $ در سطح سراسری تعریف نشده و همین موضوع منشأ بخش بزرگی از خطاهای «$ is not a function» است.
رایج‌ترین علت‌هایی که باعث می‌شوند jQuery در قالب وردپرس از کار بیفتد عبارت‌اند از: استفادهٔ نادرست از میان‌بر $ بدون رعایت no-conflict، بارگذاری همزمان دو نسخهٔ jQuery (یکی از هسته و یکی از قالب/افزونه)، ترتیب اشتباه بارگذاری اسکریپت‌ها به‌خاطر defer/async افزونه‌های سرعت، و کدهای قدیمی‌ای که از توابع حذف‌شدهٔ jQuery استفاده می‌کنند. در بخش بعد این علت‌ها را یک‌به‌یک عیب‌یابی می‌کنیم.
نمودار علت‌های کار نکردن jQuery در قالب وردپرس؛ تداخل نسخه و حالت no-conflict

مراحل عیب‌یابی و رفع مشکل jQuery (گام‌به‌گام)

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

گام اول: خطا را در کنسول مرورگر بخوانید

قبل از هر کاری، صفحه‌ای را که مشکل دارد باز کنید و با فشردن F12 یا Ctrl+Shift+I ابزار توسعه‌دهندهٔ مرورگر را باز کنید و به سربرگ Console بروید. پیام خطا معمولاً دقیقاً می‌گوید مشکل کجاست: «jQuery is not defined» یعنی خودِ کتابخانه لود نشده، «$ is not a function» یعنی مشکل از no-conflict و میان‌بر $ است، و خطای 404 روی فایل jquery یعنی مسیر بارگذاری اشکال دارد. بررسی هم‌زمان فایل ارور لاگ سایت هم کمک می‌کند ریشهٔ خطاهای سمت سرور را پیدا کنید.

گام دوم: کد را به فرم no-conflict اصلاح کنید

اگر خطای «$ is not a function» دارید، مشکل تقریباً همیشه استفاده از میان‌بر $ است. کافی است ساختار کد را طوری تغییر دهید که $ به‌عنوان پارامتر داخل تابع jQuery پاس داده شود. به‌جای $(document).ready از فرم زیر استفاده کنید:
// وردپرس jQuery را در حالت no-conflict لود می‌کند؛ پس میان‌بر $ سراسری نیست.
// به‌جای $(document).ready از فرم زیر استفاده کنید تا $ داخل تابع در دسترس باشد:
jQuery(document).ready(function ($) {
    // اینجا با خیال راحت از $ استفاده کنید
    $('.menu-toggle').on('click', function () {
        $('#main-nav').slideToggle();
    });
});
اگر کل فایل اسکریپت شما پر از $ است و نمی‌خواهید همه را تغییر دهید، می‌توانید کل کد را داخل یک تابع خوداجرا (IIFE) بپیچید و jQuery را به‌عنوان $ به آن پاس دهید تا $ در همهٔ فایل معتبر شود:
// اگر کل فایل شما از $ استفاده می‌کند، آن را در یک IIFE بپیچید:
( function ( $ ) {
    'use strict';
    $( function () {
        // کد شما؛ $ اینجا معادل jQuery است
        $( '.faq-item' ).on( 'click', function () {
            $( this ).toggleClass( 'is-open' );
        } );
    } );
} )( jQuery );

نکتهٔ مهم دربارهٔ $

این دو روش کاملاً امن‌اند و رفتار هستهٔ وردپرس را خراب نمی‌کنند. هرگز برای درست‌کردن $ سراغ حذف no-conflict نروید؛ چون ممکن است کتابخانه‌های دیگر سایت را از کار بیندازد. روش‌های امن افزودن جاوااسکریپت را در راهنمای درج جاوااسکریپت در وردپرس ببینید.

گام سوم: jQuery را به‌درستی enqueue کنید

اگر خطای «jQuery is not defined» دارید، یعنی اسکریپت شما قبل از خودِ jQuery اجرا شده است. راه درست این است که اسکریپت‌تان را با تابع رسمی wp_enqueue_script بارگذاری کنید و jQuery را به‌عنوان وابستگی اعلام کنید تا وردپرس تضمین کند jQuery همیشه اول لود می‌شود. این کد را در فایل functions.php قالب فرزند قرار دهید:
<?php
// اسکریپت سفارشی را با اعلام jquery به‌عنوان وابستگی enqueue کنید
// این کد را در functions.php قالب فرزند قرار دهید
add_action( 'wp_enqueue_scripts', 'webdade_enqueue_theme_scripts' );
function webdade_enqueue_theme_scripts() {
    wp_enqueue_script(
        'theme-main',                          // نام دلخواه اسکریپت
        get_stylesheet_directory_uri() . '/js/main.js',
        array( 'jquery' ),                     // وابستگی: jQuery حتماً اول لود می‌شود
        '1.0.0',
        true                                    // بارگذاری در فوتر
    );
}

هشدار: ویرایش نادرست functions.php سایت را از کار می‌اندازد

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

گام چهارم: تداخل افزونه یا قالب را پیدا کنید

اگر بعد از نصب یک افزونه یا فعال‌کردن قالب جدید مشکل شروع شده، احتمال تداخل بالاست. برای یافتن مقصر، افزونه‌ها را یکی‌یکی غیرفعال کنید و هر بار سایت را تست کنید؛ به‌محض اینکه مشکل برطرف شد، افزونهٔ آخر مقصر است. برای قالب هم به‌طور موقت یک قالب پیش‌فرض مثل Twenty Twenty-Five را فعال کنید. اگر با غیرفعال‌شدن یک افزونه مشکل حل شد، معمولاً آن افزونه نسخهٔ جداگانه‌ای از jQuery لود می‌کند که با هسته تداخل دارد.

گام پنجم: jQuery را از defer/async افزونهٔ سرعت مستثنا کنید

افزونه‌های بهینه‌سازی سرعت (مثل کش و minify) گاهی به همهٔ اسکریپت‌ها defer یا async می‌دهند. این کار باعث می‌شود jQuery دیرتر از اسکریپت‌هایی که به آن وابسته‌اند لود شود و خطا بدهد. راه‌حل ساده است: در تنظیمات افزونهٔ سرعت، فایل jquery.js (یا jquery.min.js و jquery-core) را به فهرست استثناهای defer/async اضافه کنید. سپس کش را کامل پاک کنید و دوباره تست بگیرید.

گام ششم: برای کدهای قدیمی از افزونهٔ Migrate کمک بگیرید

از وردپرس 5.6 نسخهٔ همراهِ jQuery به 3.5.1 ارتقا یافت و برخی توابع قدیمی حذف شدند؛ به همین دلیل قالب‌ها و افزونه‌های به‌روزنشده ممکن است دچار مشکل شوند. اگر قالب یا افزونهٔ قدیمی دارید که نمی‌توانید فوراً به‌روزش کنید، تیم وردپرس افزونهٔ رسمی و موقتی به نام Enable jQuery Migrate Helper را معرفی کرده که سازگاری با کدهای قدیمی را برمی‌گرداند. این فقط یک راهکار موقت است؛ راه‌حل اصلی، به‌روزرسانی قالب و افزونه‌هاست.
برای اینکه انتخاب راهکار ساده‌تر شود، در جدول زیر خطاهای رایج jQuery و راه‌حل هرکدام را کنار هم گذاشته‌ایم:
جدول خطاهای رایج jQuery در وردپرس و راه‌حل هر خطا در کنسول مرورگر
جدول خطاهای رایج jQuery و راه‌حل آن‌ها:
پیام خطا در کنسولعلت اصلیراه‌حل پیشنهادی
jQuery is not definedاسکریپت قبل از jQuery لود شدهبا wp_enqueue_script و وابستگی jquery بارگذاری کنید
$ is not a functionاستفاده از $ بدون رعایت no-conflictکد را به فرم jQuery(function($){…}) ببرید
Uncaught TypeError روی توابع قدیمیقالب/افزونه سازگار با jQuery 1.xقالب و افزونه را آپدیت یا Migrate Helper را فعال کنید
فایل jquery با خطای 404مسیر یا CDN اشتباه/تداخل نسخهنسخهٔ دستی را حذف و از jQuery هسته استفاده کنید
کدها فقط با افزونهٔ کش خراب می‌شوندdefer/async روی jqueryjquery.js را از defer/async مستثنا و کش را پاک کنید
جمع‌بندی جدول: ابتدا از روی پیام کنسول علت را تشخیص دهید، بعد سراغ راه‌حل مربوط به همان ردیف بروید؛ این روش سریع‌ترین مسیر رفع مشکل است.

معایب، محدودیت‌ها و نکاتی که باید صادقانه بدانید

رفع مشکل jQuery معمولاً شدنی است، اما مثل هر تغییری در وردپرس چند نکته و محدودیت دارد که بهتر است از قبل بدانید:
  • ریسک ویرایش functions.php: یک اشتباه کوچک می‌تواند سایت را با خطای 500 از دسترس خارج کند؛ بکاپ و استفاده از قالب فرزند ضروری است.
  • افزونهٔ Migrate راه‌حل دائمی نیست: فقط سازگاری موقت می‌دهد و در آینده حذف خواهد شد؛ راه‌حل واقعی به‌روزرسانی کد است.
  • قالب‌های نال‌شده و قدیمی: اگر قالب یا افزونه‌ای به‌روزرسانی نمی‌شود، این مشکل مدام برمی‌گردد و بهتر است جایگزینش کنید.
  • وابستگی به کش: بعد از هر اصلاح باید همهٔ لایه‌های کش (افزونه، مرورگر، CDN) را پاک کنید وگرنه تصور می‌کنید راه‌حل جواب نداده است.

نقل‌قول از منبع رسمی وردپرس

تیم هستهٔ وردپرس دربارهٔ ارتقای jQuery نوشته است که نسخهٔ همراهِ وردپرس در نسخهٔ 5.6 از 1.12.4-wp به 3.5.1 به‌روزرسانی شد و همین تغییر می‌تواند در قالب‌ها و افزونه‌های قدیمی «رفتارهای غیرمنتظره» ایجاد کند؛ به همین دلیل به‌روزرسانی افزونه‌ها و قالب راه‌حل منطقی است. منبع: make.wordpress.org — Updating jQuery version (2020).
پس اگر مشکل بعد از به‌روزرسانی وردپرس شروع شده، تعجب نکنید؛ این یک تغییر عمدی و مستندشده در هسته است و راه‌حل درست، هماهنگ‌کردن قالب و افزونه با نسخهٔ جدید jQuery است، نه بازگرداندن وردپرس به نسخهٔ قدیمی.

نقش هاست وردپرس وب‌داده در عیب‌یابی بی‌دردسر

عیب‌یابی jQuery وقتی راحت است که بتوانید سریع به فایل‌های سایت دسترسی داشته باشید، بکاپ بگیرید و در صورت خطا در چند دقیقه به عقب برگردید. اینجاست که کیفیت هاست خودش را نشان می‌دهد؛ چون بخش بزرگی از رفع این مشکل، ویرایش functions.php و پاک‌کردن کش است و اگر چیزی خراب شود باید بتوانید فوراً فایل را اصلاح یا نسخهٔ قبلی را بازگردانید.
در تجربهٔ پشتیبانی ما در وب‌داده، بسیاری از کاربران وردپرسی دقیقاً هنگام همین کارها به کمک نیاز دارند؛ دسترسی به File Manager سی‌پنل و امکان بکاپ سریع باعث می‌شود عیب‌یابی بدون استرس انجام شود. به همین دلیل روی این موارد تأکید داریم:
✅ هاست وردپرس وب‌داده با منابع اختصاصی و دیسک پرسرعت برای اجرای روان اسکریپت‌ها.
✅ زیرساخت نسل جدید HPE (Gen11 و Gen10) برای پایداری و پاسخ سریع سرور.
✅ دیتاسنترهای ایران، هلند و آلمان برای انتخاب نزدیک‌ترین لوکیشن به مخاطبان شما.
✅ پشتیبانی فنی ۲۴ ساعته برای کمک در ویرایش کد، بکاپ و رفع خطای احتمالی.
اگر می‌خواهید سایت وردپرسی شما روی بستری سریع و پایدار اجرا شود و عیب‌یابی‌هایی مثل همین مقاله را با خیال راحت انجام دهید، می‌توانید پلن‌های هاست سی‌پنل وب‌داده را بررسی کنید.

پرسش‌های پرتکرار دربارهٔ کار نکردن jQuery در وردپرس

جمع‌بندی و قدم بعدی شما

در این راهنما دیدیم که کار نکردن jQuery در قالب وردپرس معمولاً ریشه در چند علت مشخص دارد: استفادهٔ نادرست از میان‌بر $ بدون رعایت no-conflict، بارگذاری نادرست یا دیرهنگام jQuery، تداخل نسخه‌ها میان قالب و افزونه، و کدهای قدیمی ناسازگار با jQuery 3.x. مسیر درست این است که اول خطا را در کنسول بخوانید، بعد کد را به فرم no-conflict ببرید و با enqueue درست بارگذاری کنید، سپس تداخل افزونه/قالب و تنظیمات افزونهٔ سرعت را بررسی کنید. مهم‌ترین توصیه: قبل از هر ویرایش کدی بکاپ بگیرید و بعد از هر اصلاح، کش را کامل پاک کنید و دوباره تست بگیرید.

جمع‌بندی سریع

✅ اول خطا را در کنسول مرورگر بخوانید تا علت را دقیق بفهمید.
✅ کد را به فرم jQuery(function($){…}) یا IIFE ببرید.
✅ اسکریپت را با wp_enqueue_script و وابستگی jquery لود کنید.
✅ تداخل افزونه/قالب و defer/async افزونهٔ سرعت را بررسی و کش را پاک کنید.
در صورتی که سوالی داشتید می‌توانید در بخش نظرات با ما در ارتباط باشید.
منابع: developer.wordpress.org — wp_enqueue_script()؛ make.wordpress.org — Updating jQuery version (2020)؛ make.wordpress.org — Handling jQuery issues in 5.6 (2020)؛ WPBeginner — Fix jQuery is not defined.
به اشتراک بگذارید
وب داده
وب داده

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

مقاله‌ها: 69

نوشته‌ای مرتبط

پاسخی بگذارید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *