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

تابع wp_get_nav_menu_items() یکی از ابزارهای مهم توسعه‌دهندگان وردپرس برای دریافت آیتم‌های منو (nav menu items) به شکل برنامه‌ای است. با استفاده از این تابع می‌توانید منوها را خارج از walker پیش‌فرض وردپرس بخوانید، پردازش کنید و به شکل دلخواه رندر کنید؛ مثلاً برای مگا منوها، منوهای موبایل، یا تولید ساختار JSON برای SPAها.

معرفی کلی و پارامترها

امضای کلی تابع:

wp_get_nav_menu_items( $menu, $args = array() )

پارامترها:

• $menu: شناسهٔ منو، slug، نام یا شیء term مربوط به منو (نوع taxonomy: nav_menu).
• $args: آرایه‌ای از گزینه‌ها برای فیلتر کردن نتایج (مثل order، orderby، post_status و …). در عمل اغلب فقط از مقدار پیش‌فرض استفاده می‌شود.

آنچه تابع باز می‌گرداند

این تابع یک آرایه از شیءهای WP_Post با ساختار خاص آیتم‌های منو برمی‌گرداند. هر آیتمِ منو پس از پردازش توسط وردپرس شامل ویژگی‌هایی مثل:

مثال پایه: خواندن و نمایش ساده منو

$items = wp_get_nav_menu_items('primary'); // می‌تواند slug یا ID هم باشد

if ( $items ) {
foreach ( $items as $item ) {
echo '<a>url ) . '"&gt;' . esc_html( $item-&gt;title ) . '</a>';
}
}

این قطعه کد آیتم‌های منویی با slug یا نام primary را می‌گیرد و لینک‌های ساده را چاپ می‌کند. توجه داشته باشید که برای خروجی امن از توابع esc_url و esc_html استفاده شده است.

ساختار درختی (Nested) از آیتم‌ها

ایتم‌های منو در دیتابیس به شکل یک لیست تخت ذخیره می‌شوند که با مقدار menu_item_parent می‌توان آن‌ها را به ساختار درختی تبدیل کرد. نمونه کدی که یک آرایهٔ سلسله‌مراتبی می‌سازد:

function build_menu_tree( $items ) {
    $tree = array();
    $by_id = array();

    foreach ( $items as $item ) {
        $item->children = array();
        $by_id[ $item->ID ] = $item;
    }

    foreach ( $by_id as $id => $item ) {
        if ( $item->menu_item_parent && isset( $by_id[ $item->menu_item_parent ] ) ) {
            $by_id[ $item->menu_item_parent ]->children[] = $item;
        } else {
            $tree[] = $item;
        }
    }

    return $tree;
}

$items = wp_get_nav_menu_items('primary');
$tree = build_menu_tree( $items );

در این کد ابتدا یک نقشهٔ ID به شیء می‌سازیم، سپس هر آیتم را در فرزندِ والد مناسب قرار می‌دهیم یا به ریشه اضافه می‌کنیم. در خروجی، $tree شامل آرایه‌ای از آیتم‌های درجهٔ اول است که هرکدام ممکن است children داشته باشند.

فیلتر کردن و تغییر آیتم‌ها قبل از رندر

اگر می‌خواهید آیتم‌ها را قبل از نمایش تغییر دهید، از هوک wp_get_nav_menu_items استفاده کنید:

add_filter( 'wp_get_nav_menu_items', 'my_modify_menu_items', 10, 3 );

function my_modify_menu_items( $items, $menu, $args ) {
    foreach ( $items as $item ) {
        if ( $item->title == 'Login' && ! is_user_logged_in() ) {
            $item->title = 'ورود / ثبت‌نام';
        }
    }
    return $items;
}

این فیلتر قبل از بازگرداندن آیتم‌ها اجرا می‌شود و امکان تغییر عنوان، URL یا حذف یک آیتم را فراهم می‌کند. پارامتر $menu و $args به شما اطلاعات بیشتری دربارهٔ منوی فراخوانی‌شده می‌دهند.

نکات عملکردی و بهینه‌سازی

• تابع wp_get_nav_menu_items خودش از کش داخلی استفاده می‌کند اما اگر چند بار در یک صفحه فراخوانی می‌کنید، بهتر است نتیجه را در متغیر ذخیره کنید تا کوئری تکراری نشود.
• اگر نیاز به منوی بسیار بزرگ یا منوهای داینامیک دارید، ترجیحاً پردازش‌های سنگین را به کش‌هایی مثل Transients منتقل کنید.
• برای رندرهای سفارشی پیچیده، استفاده از walker سفارشی (extend Walker_Nav_Menu) گاهی ساده‌تر و بهینه‌تر است؛ اما وقتی کنترل کامل داده‌ها لازم باشد، wp_get_nav_menu_items همراه با رندر اختصاصی انعطاف بیشتری می‌دهد.

موارد کاربرد (Use Cases)

• ساخت مگا منو که نیاز به گروه‌بندی آیتم‌ها و درج thumbnail یا توضیحات دارد.
• تولید منوی JSON برای اپلیکیشن‌های تک‌صفحه‌ای (SPA) یا موبایل.
• نمایش منوی متفاوت بر اساس شرایط کاربر (ورود/عدم ورود، نقش کاربری، زبان سایت).
• ترکیب آیتم‌های منو با داده‌های سفارشی (meta) و نمایش فیلترشده.

نکات امنیتی و دسترسی

همیشه خروجی URL، عنوان و attributeها را با توابع esc_* مناسب پاکسازی کنید. همچنین اگر آیتم‌هایی حق‌نمایش خاصی دارند، قبل از نمایش بررسی دسترسی (capabilities) را انجام دهید تا اطلاعات حساس فاش نشود.

جمع‌بندی

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

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

ارسال