云策 WordPress 开发者社区

钩子文档

walker_nav_menu_start_el

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

概述

walker_nav_menu_start_el 是一个 WordPress 过滤器钩子，用于修改导航菜单项起始输出的 HTML。它允许开发者在菜单项输出中添加自定义内容，如额外 HTML 元素或基于条件的子菜单。

关键要点

  • 过滤器钩子名称：walker_nav_menu_start_el，在 Walker_Nav_Menu::start_el() 中调用。
  • 参数：$item_output（菜单项起始 HTML 输出）、$menu_item（菜单项数据对象，可能是 WP_Post 或 stdClass）、$depth（菜单项深度）、$args（wp_nav_menu() 参数对象）。
  • 用途：过滤菜单项输出，仅包括 $args->before、打开 <a> 标签、标题、关闭 <a> 标签和 $args->after，无直接过滤器修改 <a> 标签的开闭。
  • 注意事项：$menu_item 可能为 stdClass，避免严格类型检查；可结合 wp_nav_menu() 参数（如 menu_class、depth）进行高级定制。

代码示例

add_filter( 'walker_nav_menu_start_el', 'wpdocs_menu_item_custom_output', 10, 4 );
function wpdocs_menu_item_custom_output( $item_output, $item, $depth, $args ) {
    $menu_item_classes = $item->classes;
    if ( empty( $menu_item_classes ) || !in_array( 'menu-item-target', $menu_item_classes ) ) {
        return $item_output;
    }
    ob_start();
    ?>
    <div class="custom-sub-menu">
        <ul>
            <li><a href="#">Custom sub-menu item</a></li>
        </ul>
    </div>
    <?php
    $custom_sub_menu_html = ob_get_clean();
    $item_output .= $custom_sub_menu_html;
    return $item_output;
}
📄 原文内容

Filters a menu item’s starting output.

Description

The menu item’s starting output only includes $args->before, the opening <a>, the menu item’s title, the closing </a>, and $args->after. Currently, there is no filter for modifying the opening and closing <li> for a menu item.

Parameters

$item_outputstring
The menu item’s starting HTML output.
$menu_itemWP_Post
Menu item data object.
$depthint
Depth of menu item. Used for padding.
$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'.

Source

$output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $menu_item, $depth, $args );

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
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    damchtlv


    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

    This hook is useful when you want to add extra html to a menu item output.
    Example: add a custom sub menu based on a menu item that has a class “menu-item-target”

    /**
 *  Menu items - Add "Custom sub-menu" in menu item render output
 *  if menu item has class "menu-item-target"
 */
add_filter( 'walker_nav_menu_start_el', 'wpdocs_menu_item_custom_output', 10, 4 );
function wpdocs_menu_item_custom_output( $item_output, $item, $depth, $args ) {

    $menu_item_classes = $item->classes;
    if ( empty( $menu_item_classes ) || !in_array( 'menu-item-target', $menu_item_classes ) ) {
        return $item_output;
    }

    ob_start(); 
    ?>
    <ul class="custom-sub-menu">
        <li class="custom-menu-item">
            <a href="#custom-url">
                
            </a>
        </li>
    </ul>
     element of the menu item targeted
    $item_output .= $custom_sub_menu_html;

    return $item_output;
}