云策 WordPress 开发者社区

钩子文档

widget_nav_menu_args

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

概述

widget_nav_menu_args 是一个 WordPress 过滤器钩子，用于修改导航菜单小部件传递给 wp_nav_menu() 的参数数组。它允许开发者在菜单渲染前自定义菜单的显示和行为。

关键要点

  • 过滤器名称：widget_nav_menu_args，应用于 wp_nav_menu() 的参数数组。
  • 主要参数：$nav_menu_args（传递给 wp_nav_menu() 的参数数组）、$nav_menu（当前菜单对象）、$args（小部件显示参数）、$instance（小部件设置数组）。
  • 用途：自定义导航菜单小部件的输出，如菜单类、容器、深度、回退回调等。
  • 相关函数：与 wp_nav_menu() 和 WP_Nav_Menu_Widget::widget() 紧密关联。

代码示例

add_filter( 'widget_nav_menu_args', function( $nav_menu_args, $nav_menu, $args, $instance ) {
    // 修改参数，例如设置自定义菜单类
    $nav_menu_args['menu_class'] = 'custom-menu-class';
    return $nav_menu_args;
}, 10, 4 );

注意事项

  • 参数 $nav_menu_args 继承自 wp_nav_menu()，支持所有标准参数如 menu_class、container、depth 等。
  • 从 WordPress 4.4.0 开始添加了 $instance 参数，允许基于小部件实例进行更精细的控制。
  • 确保修改后的参数数组符合 wp_nav_menu() 的预期格式，以避免渲染错误。
📄 原文内容

Filters the arguments for the Navigation Menu widget.

Parameters

$nav_menu_argsarray
An array of arguments passed to wp_nav_menu() to retrieve a navigation menu.

  • fallback_cb callable|bool
    Callback to fire if the menu doesn’t exist. Default empty.
  • menu mixed
    Menu ID, slug, or name.

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

$nav_menuWP_Term
Nav menu object for the current menu.
$argsarray
Display arguments for the current widget.
$instancearray
Array of settings for the current widget.

Source

wp_nav_menu( apply_filters( 'widget_nav_menu_args', $nav_menu_args, $nav_menu, $args, $instance ) );

View all references View on Trac View on GitHub

Used by Description
WP_Nav_Menu_Widget::widget()wp-includes/widgets/class-wp-nav-menu-widget.php

Outputs the content for the current Navigation Menu widget instance.

Changelog

Version Description
4.4.0 Added the $instance parameter.
4.2.0 Introduced.