云策 WordPress 开发者社区

钩子文档

wp_nav_menu_items

查看官方原文 ↗
💡 云策文档标注

概述

wp_nav_menu_items 是一个 WordPress 过滤器钩子，用于修改导航菜单的 HTML 列表内容。它允许开发者在菜单输出前动态添加、移除或调整菜单项，常用于自定义菜单功能。

关键要点

  • 过滤器钩子：wp_nav_menu_items，用于过滤导航菜单的 HTML 列表内容。
  • 参数：接受两个参数：$items（菜单项的 HTML 字符串）和 $args（包含 wp_nav_menu() 参数的对象）。
  • 用途：可用于向特定菜单添加额外项目（如搜索表单、用户头像或登录链接），基于条件（如用户登录状态或菜单 ID）进行定制。
  • 调用方式：通过 add_filter() 函数添加回调函数，优先级和参数数量可指定（如 10 和 2）。

代码示例

function add_search_form($items, $args) {
    if( $args->theme_location == 'menu-1' ){
        $items .= '<li><form role="search" method="get" action="' . home_url( '/' ) . '">'
                . '<label><span class="screen-reader-text">' . _x( 'Search for:', 'label' ) . '</span></label>'
                . '<input type="search" placeholder="Search …" value="' . get_search_query() . '" name="s" />'
                . '<input type="submit" value="Search" />'
                . '</form></li>';
    }
    return $items;
}
add_filter('wp_nav_menu_items', 'add_search_form', 10, 2);

注意事项

  • 确保在 functions.php 文件中添加代码，或使用代码片段插件，以避免直接修改主题文件。
  • 使用 $args->theme_location 或 $args->menu 来指定目标菜单，需与注册的菜单位置或 ID 匹配。
  • 回调函数必须返回修改后的 $items 字符串，否则菜单内容可能丢失。
📄 原文内容

Filters the HTML list content for navigation menus.

Description

See also

Parameters

$itemsstring
The HTML list content for the menu items.
$argsstdClass
An object containing wp_nav_menu() arguments.

More Arguments from wp_nav_menu( … $args )

Array of nav menu arguments.

  • menu int|string|WP_Term
    Desired menu. Accepts a menu ID, slug, name, or object.
  • menu_class string
    CSS class to use for the ul element which forms the menu.
    Default 'menu'.
  • menu_id string
    The ID that is applied to the ul element which forms the menu.
    Default is the menu slug, incremented.
  • container string
    Whether to wrap the ul, and what to wrap it with.
    Default 'div'.
  • container_class string
    Class that is applied to the container.
    Default ‘menu-{menu slug}-container’.
  • container_id string
    The ID that is applied to the container.
  • container_aria_label string
    The aria-label attribute that is applied to the container when it’s a nav element.
  • fallback_cb callable|false
    If the menu doesn’t exist, a callback function will fire.
    Default is 'wp_page_menu'. Set to false for no fallback.
  • before string
    Text before the link markup.
  • after string
    Text after the link markup.
  • link_before string
    Text before the link text.
  • link_after string
    Text after the link text.
  • echo bool
    Whether to echo the menu or return it. Default true.
  • depth int
    How many levels of the hierarchy are to be included.
    0 means all. Default 0.
    Default 0.
  • walker object
    Instance of a custom walker class.
  • theme_location string
    Theme location to be used. Must be registered with register_nav_menu() in order to be selectable by the user.
  • items_wrap string
    How the list items should be wrapped. Uses printf() format with numbered placeholders. Default is a ul with an id and class.
  • item_spacing string
    Whether to preserve whitespace within the menu’s HTML.
    Accepts 'preserve' or 'discard'. Default 'preserve'.

Source

$items = apply_filters( 'wp_nav_menu_items', $items, $args );

View all references View on Trac View on GitHub

Used by Description
wp_nav_menu()wp-includes/nav-menu-template.php

Displays a navigation menu.

Changelog

Version Description
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    LebCit


    You must log in to vote on the helpfulness of this noteVote results for this note: 9You must log in to vote on the helpfulness of this note

    Add HTML5 search form to a menu
    Add this code to functions.php. You can completely modify the output, and style the form as you want.
    Please, don’t forget to replace the theme_location !
    For example, if the id of my menu was main-menu, I would write if( $args->theme_location == 'main-menu' )
    Hope this will help.

    function add_search_form($items, $args) {
          if( $args->theme_location == 'menu-1' ){
          $items .= '<li class="menu-item">'
                  . '<form role="search" method="get" class="search-form" action="'.home_url( '/' ).'">'
                  . '<label>'
                  . '<span class="screen-reader-text">' . _x( 'Search for:', 'label' ) . '</span>'
                  . '<input type="search" class="search-field" placeholder="' . esc_attr_x( 'Search …', 'placeholder' ) . '" value="' . get_search_query() . '" name="s" title="' . esc_attr_x( 'Search for:', 'label' ) . '" />'
                  . '</label>'
                  . '<input type="submit" class="search-submit" value="'. esc_attr_x('Search', 'submit button') .'" />'
                  . '</form>'
                  . '</li>';
          }
        return $items;
}
add_filter('wp_nav_menu_items', 'add_search_form', 10, 2);

  2. Skip to note 5 content


    arifktk


    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    Add extra menu item to a WordPress Nav Menu

    Using this code snippet, one can add an additional menu item to the end of a WordPress navigation menu. For example, here in this case I am adding a WooCommerce Login/Register link when a user is not logged in, and a My Account page link when a user is logged in.

    add_filter( 'wp_nav_menu_items', 'add_extra_item_to_nav_menu', 10, 2 );
function add_extra_item_to_nav_menu( $items, $args ) {
    if (is_user_logged_in() && $args->menu == 303) {
        $items .= '<li><a href="'. get_permalink( get_option('woocommerce_myaccount_page_id') ) .'">My Account</a></li>';
    }
    elseif (!is_user_logged_in() && $args->menu == 303) {
        $items .= '<li><a href="' . get_permalink( wc_get_page_id( 'myaccount' ) ) . '">Sign in  /  Register</a></li>';
    }
    return $items;
}

    How to use the above code?

    1. If you are using a child theme, then add this snippet to your currently active child theme’s functions.php file, otherwise, add to your currently active theme’s functions.php file. Alternatively, you can use a code snippet plugin like Code Snippets (https://wordpress.org/plugins/code-snippets/) without directly modifying your theme files.
    2. You can use theme_location or the ID of your nav menu in the if condition to specify the menu which you are adding the item to. I have used ID, if you are going to use the ID too, then change it from 303 to whatever the ID of your menu is. You can find the ID of your menu in the WP Admin panel by going to Appearance > Menus. Then select a menu from the drop-down that says: Select a menu to edit and click on the select button next to it. Now you will see the ID of your menu at the end of your current screen URL like this: https://myexampleshopsite.com/wp-admin/nav-menus.php?action=edit&menu;=303. You can see the 303 at the end, which is the ID of my menu, yours can be something different, replace with that.

    Hope this helps someone 🙂

  3. Skip to note 6 content


    omartheman949


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Used the following snippet to add a user avatar image as the last menu item. Had to use $args->menu==='main-menu' rather than 'primary' or id, as other examples did. Found this out finally by printing out $args->menu to the navbar, to see what that argument actually was.

    // register shortcode
add_shortcode('bbwp_get_session', 'bbwp_get_session'); 

add_filter( 'wp_nav_menu_items', 'add_extra_item_to_nav_menu', 10, 2 );
function add_extra_item_to_nav_menu( $items, $args ) {
	if (is_user_logged_in() && $args->menu === 'main-menu') {
		$items .= '<li class="wt_menu_item_user_avatar"><a href="/my-account">' . get_avatar( $current_user->ID, 32 ) . '</a></li>';
	}
	return $items;
}