nav_menu_css_class
云策文档标注
概述
nav_menu_css_class 是一个 WordPress 过滤器钩子，用于修改菜单项列表元素（li）的 CSS 类数组。它允许开发者基于菜单项属性、参数或主题位置动态添加或移除类，常用于自定义导航菜单样式。
关键要点
- 过滤器钩子：nav_menu_css_class，由 Walker_Nav_Menu 类调用，用于过滤菜单项的 CSS 类。
- 参数：接受 $classes（CSS 类数组）、$menu_item（WP_Post 对象）、$args（wp_nav_menu() 参数对象）和 $depth（深度，WordPress 4.1+ 添加）。
- 用途：可基于 $args->theme_location 等条件添加自定义类，实现特定菜单的样式控制。
- 版本历史：WordPress 3.0 引入，4.1.0 添加 $depth 参数。
代码示例
// 示例：为特定主题位置的菜单项添加类
function wpdocs_channel_nav_class( $classes, $item, $args ) {
if ( 'network-menu' === $args->theme_location ) {
$classes[] = "network-menu-item";
}
return $classes;
}
add_filter( 'nav_menu_css_class', 'wpdocs_channel_nav_class', 10, 4 );注意事项
- 确保函数参数数量与 add_filter 的优先级和参数数量匹配（例如，WordPress 4.1+ 使用 4 个参数）。
- 使用 $args->theme_location 可针对特定注册的菜单位置进行过滤。
- 避免过度修改类数组，以免影响默认样式和功能。
原文内容
Filters the CSS classes applied to a menu item’s list item element.
Parameters
$classesstring[]-
Array of the CSS classes that are applied to the menu item’s
<li>element. $menu_itemWP_Post-
The current menu item object.
$argsstdClass-
An object of wp_nav_menu() arguments.
More Arguments from wp_nav_menu( … $args )
Array of nav menu arguments.
menuint|string|WP_TermDesired menu. Accepts a menu ID, slug, name, or object.menu_classstringCSS class to use for the ul element which forms the menu.
Default'menu'.menu_idstringThe ID that is applied to the ul element which forms the menu.
Default is the menu slug, incremented.containerstringWhether to wrap the ul, and what to wrap it with.
Default'div'.container_classstringClass that is applied to the container.
Default ‘menu-{menu slug}-container’.container_idstringThe ID that is applied to the container.container_aria_labelstringThe aria-label attribute that is applied to the container when it’s a nav element.fallback_cbcallable|falseIf the menu doesn’t exist, a callback function will fire.
Default is'wp_page_menu'. Set to false for no fallback.beforestringText before the link markup.afterstringText after the link markup.link_beforestringText before the link text.link_afterstringText after the link text.echoboolWhether to echo the menu or return it. Default true.depthintHow many levels of the hierarchy are to be included.
0 means all. Default 0.
Default 0.walkerobjectInstance of a custom walker class.theme_locationstringTheme location to be used. Must be registered with register_nav_menu() in order to be selectable by the user.items_wrapstringHow the list items should be wrapped. Uses printf() format with numbered placeholders. Default is a ul with an id and class.item_spacingstringWhether to preserve whitespace within the menu’s HTML.
Accepts'preserve'or'discard'. Default'preserve'.
$depthint-
Depth of menu item. Used for padding.
Source
$class_names = implode( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $menu_item, $args, $depth ) );
Skip to note 8 content
Aamer Shahzad
Apply classes to a specific menu (theme location). WordPress 4.1 or higher.
function wpdocs_channel_nav_class( $classes, $item, $args ) { if ( 'network-menu' === $args->theme_location ) { $classes[] = "network-menu-item"; } return $classes; } add_filter( 'nav_menu_css_class' , 'wpdocs_channel_nav_class' , 10, 4 );Skip to note 9 content
Steven Lin
Example code migrated from Codex:
You can use information from the
$argsparameter to conditionally filter classes based on properties of the menu that contains the items.function my_secondary_menu_classes( $classes, $item, $args ) { // Only affect the menu placed in the 'secondary' wp_nav_bar() theme location if ( 'secondary' === $args->theme_location ) { // Make these items 3-columns wide in Bootstrap $classes[] = 'col-md-3'; } return $classes; } add_filter( 'nav_menu_css_class', 'my_secondary_menu_classes', 10, 3 );Skip to note 10 content
Shah Alom
Basic Usage:
Skip to note 11 content
Steven Lin
Example migrated from Codex:
The following example adds a unique CSS class to a single, specific nav menu item.
function my_special_nav_class( $classes, $item ) { if ( is_single() && $item->title == 'Blog' ) { $classes[] = 'special-class'; } return $classes; } add_filter( 'nav_menu_css_class', 'my_special_nav_class', 10, 2 );Skip to note 12 content
Ahmad Karim
This example adds the menu items title (slug) as a class to every menu item.
function wpdocs_menu_item_title_css_class( $classes, $item ) { $classes[] = 'menu-item_' . sanitize_html_class( sanitize_title( $item->title ) ); return $classes; } add_filter( 'nav_menu_css_class', 'wpdocs_menu_item_title_css_class', 10, 2 );Skip to note 13 content
Mehedi
function wpdocs_menu_item_class( $classes, $item, $args ) { if ( 'topmenu' === $args->theme_location ) { $classes[] = 'list-inline-item'; } return $classes; } add_action( 'nav_menu_css_class', 'wpdocs_menu_item_class', 10, 3 );Skip to note 14 content
Md Afsar Uddin
Into wp nav li additional class add, it will support wordpress 4.1 or higher
function wpdocs_nav_on_li_class( $classes, $item, $args ) { if ( 'menu-1' === $args->theme_location ) { $classes[] = "header__menu--link"; } return $classes; } add_filter( 'nav_menu_css_class', 'wpdocs_nav_on_li_class', 10, 3 );