云策 WordPress 开发者社区

钩子文档

nav_menu_item_title

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

概述

nav_menu_item_title 是一个 WordPress 过滤器钩子，用于修改导航菜单项的标题输出。它允许开发者在菜单项标题渲染前进行自定义处理，例如添加额外 HTML 元素或调整内容。

关键要点

  • 过滤器钩子：nav_menu_item_title，用于过滤菜单项标题字符串。
  • 参数：$title（标题字符串）、$menu_item（WP_Post 对象）、$args（wp_nav_menu() 参数对象）、$depth（菜单项深度）。
  • 应用场景：可基于菜单项属性（如是否有子菜单）动态修改标题，例如添加下拉箭头图标。
  • 替代方案：对于简单添加内容，可考虑使用 wp_nav_menu() 的 after 或 link_after 参数。

代码示例

/**
 * Add a dropdown arrow in the navigation menu, for menu items that 
 * have a dropdown sub-menu. Returns all other menu item titles unchanged.
 * 
 * @param string   $title     The menu item's title.
 * @param WP_Post  $menu_item The current menu item object.
 * 
 * @return string
 */
function wpdocs_nav_menu_add_dropdown_arrow( $title, $menu_item ) {

	$menu_item_classes = $menu_item->classes;

	// If menu item doesn't have any classes or children, return unchanged title.
	if ( empty( $menu_item_classes ) || ! in_array( 'menu-item-has-children', $menu_item_classes ) ) {
		return $title;
	}

	// Add div around original text to separate it from down arrow 
	// (if you need a way to select only the text with CSS)
	$output_title  = '';
	$output_title .= $title;
	$output_title .= '';

	// Add downward arrow HTML
	$output_title .= ; 
	
	return $output_title;
}

add_filter( 'nav_menu_item_title', 'wpdocs_nav_menu_add_dropdown_arrow', 10, 2 );

注意事项

  • 确保过滤器函数返回修改后的标题字符串，否则可能影响菜单显示。
  • 使用前检查 $menu_item 对象属性，避免对非目标菜单项进行不必要的修改。
  • 此钩子自 WordPress 4.4.0 版本引入，兼容性需考虑。
📄 原文内容

Filters a menu item’s title.

Parameters

$titlestring
The menu item’s title.
$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.

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

$depthint
Depth of menu item. Used for padding.

Source

$title = apply_filters( 'nav_menu_item_title', $title, $menu_item, $args, $depth );

View all references View on Trac View on GitHub

Used by Description
Walker_Nav_Menu::start_el()wp-includes/class-walker-nav-menu.php

Starts the element output.

Changelog

Version Description
4.4.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    jichanbachan


    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

    You can use this hook to add HTML elements into the tag of a specific type of nav menu item.
    For example, if you have items in the nav menu that act as dropdown menus, you may want to add a HTML element that displays a downward arrow beside only those menu items, while keeping the other menu items unchanged.

    If you just want to add something to the end of all menu items, you can instead use the after or link_after arguments when calling wp_nav_menu().

    functions.php

    /**
 * Add a dropdown arrow in the navigation menu, for menu items that 
 * have a dropdown sub-menu. Returns all other menu item titles unchanged.
 * 
 * @param string   $title     The menu item's title.
 * @param WP_Post  $menu_item The current menu item object.
 * 
 * @return string
 */
function wpdocs_nav_menu_add_dropdown_arrow( $title, $menu_item ) {

	$menu_item_classes = $menu_item->classes;

	// If menu item doesn't have any classes or children, return unchanged title.
	if ( empty( $menu_item_classes ) || ! in_array( 'menu-item-has-children', $menu_item_classes ) ) {
		return $title;
	}

	// Add div around original text to separate it from down arrow 
	// (if you need a way to select only the text with CSS)
	$output_title  = '<div class="menu-item-has-children-text">';
	$output_title .= $title;
	$output_title .= '</div>';

	// Add downward arrow HTML
	$output_title .= <img src="./downarrow.jpg" />; 
	
	return $output_title;
}

add_filter( 'nav_menu_item_title', 'wpdocs_nav_menu_add_dropdown_arrow', 10, 2 );