云策 WordPress 开发者社区

函数文档

wp_get_nav_menu_object()

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

概述

wp_get_nav_menu_object() 函数用于根据菜单 ID、slug、名称或对象返回一个导航菜单对象。它通过多种方式尝试获取菜单对象，并在失败时返回 false。

关键要点

  • 参数 $menu 可以是整数、字符串或 WP_Term 对象，表示菜单的 ID、slug、名称或对象本身。
  • 返回值是 WP_Term 对象（成功时）或 false（参数未提供或菜单不存在时）。
  • 函数内部使用 get_term() 和 get_term_by() 来查找菜单，并支持通过 'wp_get_nav_menu_object' 过滤器进行自定义。

代码示例

// 通过名称获取菜单对象
$menu = wp_get_nav_menu_object( 'wpdocs mainmenu' );

// 通过 slug 获取菜单对象
$menu = wp_get_nav_menu_object( 'wpdocs-mainmenu' );

// 通过 ID 获取菜单对象
$menu_name = 'wpdocs mainmenu';
$menu_obj  = get_term_by( 'name', $menu_name, 'nav_menu' );
$menu_id   = $menu_obj->term_id;
$menu = wp_get_nav_menu_object( $menu_id );

// 通过菜单位置获取菜单对象
$menu_name = 'primary';
$locations = get_nav_menu_locations();
$menu_id   = $locations[ $menu_name ] ;
wp_get_nav_menu_object( $menu_id );
📄 原文内容

Returns a navigation menu object.

Parameters

$menuint|string|WP_Termrequired
Menu ID, slug, name, or object.

Return

WP_Term|false Menu object on success, false if $menu param isn’t supplied or term does not exist.

Source

function wp_get_nav_menu_object( $menu ) {
	$menu_obj = false;

	if ( is_object( $menu ) ) {
		$menu_obj = $menu;
	}

	if ( $menu && ! $menu_obj ) {
		$menu_obj = get_term( $menu, 'nav_menu' );

		if ( ! $menu_obj ) {
			$menu_obj = get_term_by( 'slug', $menu, 'nav_menu' );
		}

		if ( ! $menu_obj ) {
			$menu_obj = get_term_by( 'name', $menu, 'nav_menu' );
		}
	}

	if ( ! $menu_obj || is_wp_error( $menu_obj ) ) {
		$menu_obj = false;
	}

	/**
	 * Filters the nav_menu term retrieved for wp_get_nav_menu_object().
	 *
	 * @since 4.3.0
	 *
	 * @param WP_Term|false      $menu_obj Term from nav_menu taxonomy, or false if nothing had been found.
	 * @param int|string|WP_Term $menu     The menu ID, slug, name, or object passed to wp_get_nav_menu_object().
	 */
	return apply_filters( 'wp_get_nav_menu_object', $menu_obj, $menu );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_get_nav_menu_object’, WP_Term|false $menu_obj, int|string|WP_Term $menu )

Filters the nav_menu term retrieved for wp_get_nav_menu_object() .

Uses Description
get_term_by()wp-includes/taxonomy.php

Gets all term data from database by term field and data.
get_term()wp-includes/taxonomy.php

Gets all term data from database by term ID.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

Show 2 moreShow less

Used by Description
WP_Navigation_Fallback::get_nav_menu_at_primary_location()wp-includes/class-wp-navigation-fallback.php

Gets the classic menu assigned to the primary navigation menu location if it exists.
WP_REST_Menus_Controller::get_term()wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php

Gets the term, if the ID is valid.
WP_REST_Menus_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php

Prepares a single term output for response.
WP_REST_Menus_Controller::create_item()wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php

Creates a single term in a taxonomy.
wp_get_nav_menu_name()wp-includes/nav-menu.php

Returns the name of a navigation menu.
WP_Customize_Nav_Menu_Setting::value()wp-includes/customize/class-wp-customize-nav-menu-setting.php

Get the instance data for a given widget setting.
wp_get_nav_menu_to_edit()wp-admin/includes/nav-menu.php

Returns the menu formatted to edit.
WP_Nav_Menu_Widget::widget()wp-includes/widgets/class-wp-nav-menu-widget.php

Outputs the content for the current Navigation Menu widget instance.
wp_nav_menu()wp-includes/nav-menu-template.php

Displays a navigation menu.
wp_delete_nav_menu()wp-includes/nav-menu.php

Deletes a navigation menu.
wp_update_nav_menu_object()wp-includes/nav-menu.php

Saves the properties of a menu or create a new menu with those properties.
wp_update_nav_menu_item()wp-includes/nav-menu.php

Saves the properties of a menu item or create a new one.
wp_get_nav_menu_items()wp-includes/nav-menu.php

Retrieves all menu items of a navigation menu.
is_nav_menu()wp-includes/nav-menu.php

Determines whether the given ID is a navigation menu.

Show 9 moreShow less

Changelog

Version Description
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    Examples

    // By name.
$menu = wp_get_nav_menu_object( 'wpdocs mainmenu' );

// By slug.
$menu = wp_get_nav_menu_object( 'wpdocs-mainmenu' );

// By ID.
$menu_name = 'wpdocs mainmenu';
$menu_obj  = get_term_by( 'name', $menu_name, 'nav_menu' );
$menu_id   = $menu_obj->term_id;
$menu = wp_get_nav_menu_object( $menu_id );


// By location.
$menu_name = 'primary';
$locations = get_nav_menu_locations();
$menu_id   = $locations[ $menu_name ] ;
wp_get_nav_menu_object( $menu_id );