wp_nav_menu_args

💡 云策文档标注

概述

wp_nav_menu_args 是一个 WordPress 过滤器，用于在 wp_nav_menu() 函数处理参数之前修改导航菜单的显示参数。开发者可通过此过滤器在子主题或插件中动态调整菜单的配置，如添加类、ID 或使用自定义 walker 对象。

关键要点

过滤器名称：wp_nav_menu_args，应用于 wp_nav_menu() 函数的参数数组。
主要用途：允许修改菜单参数，例如 menu_class、container、depth、walker 等，以自定义菜单的 HTML 结构和行为。
应用场景：常用于子主题中覆盖父主题的菜单设置，或插件中全局调整菜单样式。
参数类型：接受数组参数，包含 menu、menu_class、container、depth、theme_location 等键值对。
返回值：必须返回修改后的参数数组，否则过滤器无效。

代码示例

// 示例1：填充缺失的 theme_location 参数
function wp_nav_menu_populate_missing_theme_location( $args ) {
    if ( ! isset( $args['theme_location'] ) || $args['theme_location'] == "" ) {
        $args['theme_location'] = 'main_navigation';
    }
    return $args;
}
add_filter( 'wp_nav_menu_args', 'wp_nav_menu_populate_missing_theme_location' );

// 示例2：修改特定主题位置的菜单参数
add_filter( 'wp_nav_menu_args', 'modify_nav_menu_args' );
function modify_nav_menu_args( $args ) {
    if( 'primary' == $args['theme_location'] ) {
        $args['depth'] = -1;
        $args['container_id'] = 'my_primary_menu';
    }
    return $args;
}

注意事项

确保在调用 wp_nav_menu() 之前应用此过滤器，通常通过 add_filter() 在 functions.php 中实现。
修改参数时需检查键是否存在，避免未定义索引错误，如使用 isset() 函数。
theme_location 参数必须已通过 register_nav_menu() 注册，否则可能无法生效。
容器 ID 等设置仅在菜单实际显示时才会应用，需确保菜单已分配。

📄 原文内容

Filters the arguments used to display a navigation menu.

Description

Parameters

$argsarray

Array of 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'.

More Information

The “wp_nav_menu_args” filter is applied to the arguments of the wp_nav_menu() function before they are processed.

This filter can be used in functions.php of a child theme to add/remove/modify the arguments of a menu defined in the parent theme.

Also, plugins can use this filter to change menus by adding classes/IDs or using a custom walker object.

Source

$args = apply_filters( 'wp_nav_menu_args', $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

Skip to note 3 content

megamenu

6 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
The following code will populate the “theme_location” option if it was not specified (or was left empty) in the initial call to “wp_nav_menu”.
```
function wp_nav_menu_populate_missing_theme_location( $args ) {
	if ( ! isset( $args['theme_location'] ) || $args['theme_location'] == "" ) {
		$args['theme_location'] = 'main_navigation';
	}
	
	return $args;
}
add_filter( 'wp_nav_menu_args', 'wp_nav_menu_populate_missing_theme_location' );
```
Log in to add feedback
Skip to note 4 content

Steven Lin

5 years ago

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
Example migrated from Codex:

The Twenty Thirteen theme defines the following menu in its header.php file.
```
 'primary', 'menu_class' => 'nav-menu' ) ); ?>
```
The following example code will add an ID to the container and change the “depth” to -1 so that links at all levels are displayed in a single, flat list.
```
add_filter( 'wp_nav_menu_args', 'modify_nav_menu_args' );

function modify_nav_menu_args( $args )
{
	if( 'primary' == $args['theme_location'] )
	{
		$args['depth'] = -1;
		$args['container_id'] = 'my_primary_menu';
	}

	return $args;
}
```
The container ID will only show up if you set a menu for this theme location.
Log in to add feedback

云策 WordPress 开发者社区

钩子文档