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

تابع is_main_query() یکی از ابزارهای مهم توسعه‌دهندگان قالب و افزونه در وردپرس است. این تابع به شما کمک می‌کند که تشخیص دهید آیا کوئری‌ای که در حال اجراست، همان کوئری اصلی (Main Query) وردپرس است یا نه. شناخت تفاوت کوئری اصلی با کوئری‌های ثانویه و یادگیری کاربرد درست is_main_query() باعث می‌شود تغییرات شما روی نتایج صفحه به‌صورت امن و بهینه اعمال شود.

کوئری اصلی (Main Query) چیست؟

وقتی وردپرس یک صفحه را بارگذاری می‌کند، یک شیء WP_Query پیش‌فرض ساخته می‌شود که تعیین می‌کند چه پست‌هایی نمایش داده شوند. این شیء را «کوئری اصلی» می‌نامیم. مثال: صفحهٔ آرشیو، صفحهٔ خانه، نتایج جستجو و صفحهٔ تک نوشته همگی توسط کوئری اصلی تولید می‌شوند.

چرا باید is_main_query() را استفاده کنیم؟

• اجتناب از تغییر کوئری‌های ثانویه (مثل WP_Query سفارشی) که ممکن است در قالب یا افزونه‌ها ایجاد شده باشد.
• اعمال تغییرات فقط روی خروجی پیش‌فرض وردپرس (مثل تغییر تعداد پست‌ها در صفحهٔ خانه).
• کاهش خطاها و جلوگیری از تداخل با افزونه‌ها یا سایر کوئری‌ها.

موقعیت مناسب استفاده: فیلتر pre_get_posts

معمول‌ترین و ایمن‌ترین مکان برای استفاده از is_main_query()، هوک pre_get_posts است. این هوک قبل از اجرای کوئری اجرا می‌شود و یک شیء WP_Query به تابع شما ارسال می‌کند. شما می‌توانید بررسی کنید که آیا این شیء، کوئری اصلی است و سپس پارامترهای آن را تغییر دهید.

function my_modify_main_query( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    if ( $query->is_home() ) {
        $query->set( 'posts_per_page', 6 );
    }
}
add_action( 'pre_get_posts', 'my_modify_main_query' );

توضیح: این کد در هوک pre_get_posts بررسی می‌کند که آیا درخواست سمت مدیریت نیست (is_admin()) و آیا کوئری، کوئری اصلی است. سپس برای صفحهٔ خانه (is_home()) تعداد پست‌ها را به 6 تغییر می‌دهد. استفاده از شرط is_admin() از تأثیر بر بخش مدیریت جلوگیری می‌کند.

مثال: تغییر نوع پست در آرشیو یک Custom Post Type

function my_cpt_archive_query( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    if ( $query->is_post_type_archive( 'book' ) ) {
        $query->set( 'posts_per_page', 12 );
        $query->set( 'orderby', 'meta_value_num' );
        $query->set( 'meta_key', 'book_rating' );
        $query->set( 'order', 'DESC' );
    }
}
add_action( 'pre_get_posts', 'my_cpt_archive_query' );

توضیح: این مثال برای آرشیو نوع نوشتهٔ «book» تعداد آیتم‌ها را تنظیم و بر اساس متای «book_rating» مرتب می‌کند. شرط $query->is_post_type_archive( 'book' ) و $query->is_main_query() تضمین می‌کند تغییر فقط روی کوئری اصلی آرشیو اعمال شود.

اشتباهات رایج و راه‌حل‌ها

• استفاده از query_posts(): این تابع کوئری اصلی را مجدداً بازنویسی می‌کند و اغلب باعث مشکلاتی مثل تداخل با صفحه‌بندی می‌شود. بهتر است از pre_get_posts یا WP_Query استفاده کنید.
• نادیده گرفتن is_main_query() در pre_get_posts: اگر شرط بررسی کوئری اصلی نباشد، ممکن است کوئری‌های ویجت‌ها یا کوئری‌های داخلی دیگر هم تغییر کنند.
• استفاده از is_main_query() در خارج از زمینهٔ مناسب: این تابع متد از کلاس WP_Query است؛ برای بررسی کوئری جاری در قالب می‌توانید از global $wp_query; $wp_query->is_main_query() استفاده کنید، اما اغلب بهتر است تغییرات را در pre_get_posts اعمال کنید.

مقایسهٔ سریع توابع مرتبط

نمونهٔ کاربردی دیگر: جلوگیری از تغییر در صفحه‌های صفحه‌بندی

function fix_paged_main_query( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    if ( $query->is_home() && ! is_paged() ) {
        $query->set( 'posts_per_page', 5 );
    }
}
add_action( 'pre_get_posts', 'fix_paged_main_query' );

توضیح: این کد فقط در صفحهٔ اول ناحیهٔ بلاگ تعداد پست‌ها را تغییر می‌دهد و از تغییر تنظیمات در صفحه‌های صفحه‌بندی شده جلوگیری می‌کند. استفاده از is_paged() کمک می‌کند تا رفتار صفحه‌بندی دست‌نخورده باقی بماند.

نتیجه‌گیری و نکات حرفه‌ای

• همیشه تغییرات کوئری را در pre_get_posts انجام دهید و is_main_query() را برای محدودسازی به کوئری اصلی استفاده کنید.
• برای کوئری‌های سفارشی (مثلاً نمایش بخشی از پست‌ها در سایدبار) از WP_Query یا get_posts() استفاده کنید تا کوئری اصلی دست‌نخورده بماند.
• در توسعه افزونه‌ها مراقب باشید که تغییرات شما با سایر افزونه‌ها تداخل نداشته باشد؛ استفاده از اولویت مناسب در add_action و شرط‌های دقیق کمک‌کننده است.

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

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

ارسال