详解 WordPress `wp_nav_menu_args` 过滤器源码：如何修改菜单渲染的参数。

WordPress 菜单改造计划：wp_nav_menu_args 过滤器源码深度剖析

大家好，我是你们今天的菜单改造大师。今天咱们要聊聊 WordPress 菜单的那些事儿，特别是那个神秘又强大的 wp_nav_menu_args 过滤器。别怕，听起来高大上，其实就像给菜谱加点自己的佐料，让菜单更符合你的口味！

WordPress 的菜单系统非常灵活，但有时候，你可能需要对默认的菜单渲染方式进行一些定制。比如，你想修改菜单容器的 class 名称，或者你想添加一些额外的属性。这时候，wp_nav_menu_args 过滤器就派上大用场了。

1. wp_nav_menu() 函数：菜单渲染的幕后英雄

要了解 wp_nav_menu_args 过滤器，首先得认识一下 wp_nav_menu() 函数。这个函数是 WordPress 中显示菜单的核心函数。简单来说，它负责从数据库中获取菜单项，然后根据你提供的参数，将它们渲染成 HTML 代码。

wp_nav_menu() 函数接收一个参数数组 $args，这个数组包含了各种控制菜单显示方式的选项。例如：

• menu：指定要显示的菜单名称、ID 或 slug。
• container：指定菜单容器的 HTML 标签名称（默认是 div）。
• container_class：指定菜单容器的 CSS class 名称（默认是 menu-{menu slug}-container）。
• container_id：指定菜单容器的 HTML ID。
• menu_class：指定菜单 ul 标签的 CSS class 名称（默认是 menu）。
• menu_id：指定菜单 ul 标签的 HTML ID。
• echo：是否直接输出菜单 HTML 代码（默认是 true）。
• fallback_cb：如果菜单不存在，则执行的回调函数（默认是 wp_page_menu）。
• before：在链接文本之前添加的内容。
• after：在链接文本之后添加的内容。
• link_before：在链接文本内部之前添加的内容。
• link_after：在链接文本内部之后添加的内容。
• depth：菜单的深度（默认是 0，表示显示所有层级）。
• walker：用于遍历菜单项的 Walker 对象（后面会详细介绍）。
• theme_location：主题位置，用于指定要显示哪个主题菜单。

这些参数足以让你对菜单进行基本的定制。但是，如果你想做更深入的修改，比如动态地修改 container_class，或者根据用户角色添加不同的 class，就需要使用 wp_nav_menu_args 过滤器了。

2. wp_nav_menu_args 过滤器：掌控菜单参数的利器

wp_nav_menu_args 过滤器允许你在 wp_nav_menu() 函数执行之前，修改传递给它的 $args 数组。换句话说，你可以拦截菜单参数，并根据自己的需求进行修改。

这个过滤器接收一个参数：

• $args (array): 传递给 wp_nav_menu() 函数的参数数组。

它必须返回修改后的 $args 数组。

源码追踪

要了解 wp_nav_menu_args 过滤器的作用位置，我们来简单追踪一下 wp_nav_menu() 函数的源码（位于 wp-includes/nav-menu-template.php）。

function wp_nav_menu( $args = array() ) {
    // ... 一些参数处理 ...

    $args = wp_parse_args( $args, $defaults );
    $args = apply_filters( 'wp_nav_menu_args', $args ); // 重点在这里！

    // ... 后续的菜单渲染逻辑 ...
}

可以看到，在 wp_nav_menu() 函数内部，$args 数组首先经过 wp_parse_args() 函数与默认参数合并，然后就会被 apply_filters( 'wp_nav_menu_args', $args ) 过滤。这意味着，你可以在这里对 $args 数组进行任意修改。

使用示例：修改菜单容器的 class 名称

假设你想把菜单容器的 class 名称从默认的 menu-{menu slug}-container 修改为 my-custom-menu-container，你可以这样做：

add_filter( 'wp_nav_menu_args', 'my_custom_menu_args' );

function my_custom_menu_args( $args ) {
    $args['container_class'] = 'my-custom-menu-container';
    return $args;
}

这段代码首先使用 add_filter() 函数将 my_custom_menu_args() 函数注册为 wp_nav_menu_args 过滤器的回调函数。然后，在 my_custom_menu_args() 函数中，我们将 $args['container_class'] 的值修改为 my-custom-menu-container，并返回修改后的 $args 数组。

是不是很简单？

更高级的用法：根据用户角色添加不同的 class

现在，我们来尝试一个更高级的用法。假设你想根据用户的角色，为菜单容器添加不同的 class。比如，如果用户是管理员，就添加 admin-menu class，如果用户是普通用户，就添加 user-menu class。

add_filter( 'wp_nav_menu_args', 'my_conditional_menu_args' );

function my_conditional_menu_args( $args ) {
    if ( is_user_logged_in() ) {
        $user = wp_get_current_user();
        if ( in_array( 'administrator', (array) $user->roles ) ) {
            $args['container_class'] .= ' admin-menu'; // 注意这里使用 .= 追加 class
        } else {
            $args['container_class'] .= ' user-menu';
        }
    } else {
        $args['container_class'] .= ' guest-menu'; // 未登录用户
    }

    return $args;
}

这段代码首先检查用户是否已登录。如果已登录，则获取当前用户对象，并检查用户是否具有 administrator 角色。如果是，则将 admin-menu class 追加到 $args['container_class'] 的值中。否则，将 user-menu class 追加到 $args['container_class'] 的值中。 如果未登录，则添加 guest-menu class。

注意： 这里使用了 .= 运算符来追加 class，而不是直接赋值。这是为了避免覆盖原有的 class 名称。

3. Walker 类：深入菜单结构的核心

除了修改 $args 数组，你还可以使用 Walker 类来更深入地定制菜单的渲染方式。Walker 类是一个用于遍历树状结构的抽象类。在 WordPress 中，它被用于遍历菜单项的层级结构，并生成相应的 HTML 代码。

WordPress 默认的菜单 Walker 类是 Walker_Nav_Menu。你可以创建自己的 Walker 类，继承 Walker_Nav_Menu，并重写其中的方法，来实现自定义的菜单渲染逻辑。

Walker_Nav_Menu 类的重要方法

• start_lvl( &$output, $depth = 0, $args = array() )：在开始一个菜单层级时调用。
• end_lvl( &$output, $depth = 0, $args = array() )：在结束一个菜单层级时调用。
• start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 )：在开始一个菜单项时调用。
• end_el( &$output, $item, $depth = 0, $args = array() )：在结束一个菜单项时调用。

通过重写这些方法，你可以完全控制菜单项的 HTML 代码生成过程。

使用示例：自定义菜单项的 HTML 代码

假设你想在每个菜单项的链接文本后面添加一个图标，你可以这样做：

class My_Custom_Menu_Walker extends Walker_Nav_Menu {
    function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
        parent::start_el( $output, $item, $depth, $args, $id );
        $output .= '<span class="menu-icon"></span>'; // 添加图标
    }
}

add_filter( 'wp_nav_menu_args', 'my_custom_walker_args' );

function my_custom_walker_args( $args ) {
    $args['walker'] = new My_Custom_Menu_Walker();
    return $args;
}

这段代码首先定义了一个名为 My_Custom_Menu_Walker 的类，继承自 Walker_Nav_Menu。然后，我们重写了 start_el() 方法，在菜单项的链接文本后面添加了一个 span 标签，用于显示图标。

接下来，我们使用 add_filter() 函数将 my_custom_walker_args() 函数注册为 wp_nav_menu_args 过滤器的回调函数。在 my_custom_walker_args() 函数中，我们将 $args['walker'] 的值设置为 My_Custom_Menu_Walker 类的实例。

这样，WordPress 在渲染菜单时，就会使用我们自定义的 Walker 类，从而在每个菜单项的链接文本后面添加一个图标。

表格总结：wp_nav_menu_args 过滤器与 Walker 类的比较

特性	wp_nav_menu_args 过滤器	Walker 类

需要注意的点：

• 在自定义 Walker 类中，$output 变量是一个字符串，用于累积最终的 HTML 代码。
• $item 变量包含了当前菜单项的各种属性，比如 ID、title、URL 等。
• $depth 变量表示当前菜单项的深度。
• $args 变量包含了传递给 wp_nav_menu() 函数的参数数组。
• $id 变量是当前菜单项的 ID。

4. 实战案例：添加 Font Awesome 图标到菜单项

现在，我们来一个更有趣的实战案例：将 Font Awesome 图标添加到菜单项。

首先，你需要确保你的 WordPress 主题已经包含了 Font Awesome。如果没有，你可以手动引入 Font Awesome 的 CSS 文件，或者使用一些插件来自动引入。

然后，你可以按照以下步骤进行操作：

1. 创建一个新的 Walker 类：

class My_Awesome_Menu_Walker extends Walker_Nav_Menu {
    function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
        $item_output = '';

        // 如果菜单项的 title 包含 "fa-"，则将其作为 Font Awesome 图标的 class 名称
        if ( strpos( $item->title, 'fa-' ) !== false ) {
            $icon_class = $item->title;
            $item->title = $item->title_attribute; // 使用 title 属性作为链接文本
        } else {
            $icon_class = '';
        }

        if ( ! empty( $icon_class ) ) {
            $attributes  = ! empty( $item->attr_title ) ? ' title="'  . esc_attr( $item->attr_title ) .'"' : '';
            $attributes .= ! empty( $item->target )     ? ' target="' . esc_attr( $item->target     ) .'"' : '';
            $attributes .= ! empty( $item->xfn )        ? ' rel="'    . esc_attr( $item->xfn        ) .'"' : '';
            $attributes .= ! empty( $item->url )        ? ' href="'   .