云策 WordPress 开发者社区

函数文档

wp_update_nav_menu_object()

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

概述

wp_update_nav_menu_object() 函数用于保存导航菜单的属性或基于这些属性创建新菜单。它处理菜单的创建和更新逻辑，包括名称冲突检查和触发相关动作钩子。

关键要点

  • 函数接受两个参数：$menu_id（菜单ID，为0时创建新菜单）和 $menu_data（菜单数据数组，需预转义）。
  • 返回值为整数（成功时的菜单ID）或 WP_Error 对象（失败时）。
  • 内部使用 wp_get_nav_menu_object() 检查菜单是否存在，并通过 wp_insert_term() 或 wp_update_term() 执行创建或更新操作。
  • 包含名称冲突验证，防止菜单名称重复。
  • 触发 wp_create_nav_menu 和 wp_update_nav_menu 动作钩子，便于开发者扩展功能。

代码示例

function wp_update_nav_menu_object( $menu_id = 0, $menu_data = array() ) {
    // 代码逻辑包括参数处理、菜单存在性检查、名称冲突验证、创建或更新菜单等。
    // 具体实现参考文档正文中的源代码。
}

注意事项

  • $menu_data 参数需预转义（pre-slashed），以避免安全风险。
  • 在创建新菜单时，如果菜单名称已存在，函数会返回 WP_Error 对象。
  • 函数依赖于 WordPress 的术语系统（taxonomy），使用 nav_menu 作为分类法。
📄 原文内容

Saves the properties of a menu or create a new menu with those properties.

Description

Note that $menu_data is expected to be pre-slashed.

Parameters

$menu_idintrequired
The ID of the menu or “0” to create a new menu.
$menu_dataarrayoptional
The array of menu data.

Default:array()

Return

int|WP_Error Menu ID on success, WP_Error object on failure.

Source

function wp_update_nav_menu_object( $menu_id = 0, $menu_data = array() ) {
	// expected_slashed ($menu_data)
	$menu_id = (int) $menu_id;

	$_menu = wp_get_nav_menu_object( $menu_id );

	$args = array(
		'description' => ( isset( $menu_data['description'] ) ? $menu_data['description'] : '' ),
		'name'        => ( isset( $menu_data['menu-name'] ) ? $menu_data['menu-name'] : '' ),
		'parent'      => ( isset( $menu_data['parent'] ) ? (int) $menu_data['parent'] : 0 ),
		'slug'        => null,
	);

	// Double-check that we're not going to have one menu take the name of another.
	$_possible_existing = get_term_by( 'name', $menu_data['menu-name'], 'nav_menu' );
	if (
		$_possible_existing &&
		! is_wp_error( $_possible_existing ) &&
		isset( $_possible_existing->term_id ) &&
		$_possible_existing->term_id !== $menu_id
	) {
		return new WP_Error(
			'menu_exists',
			sprintf(
				/* translators: %s: Menu name. */
				__( 'The menu name %s conflicts with another menu name. Please try another.' ),
				'<strong>' . esc_html( $menu_data['menu-name'] ) . '</strong>'
			)
		);
	}

	// Menu doesn't already exist, so create a new menu.
	if ( ! $_menu || is_wp_error( $_menu ) ) {
		$menu_exists = get_term_by( 'name', $menu_data['menu-name'], 'nav_menu' );

		if ( $menu_exists ) {
			return new WP_Error(
				'menu_exists',
				sprintf(
					/* translators: %s: Menu name. */
					__( 'The menu name %s conflicts with another menu name. Please try another.' ),
					'<strong>' . esc_html( $menu_data['menu-name'] ) . '</strong>'
				)
			);
		}

		$_menu = wp_insert_term( $menu_data['menu-name'], 'nav_menu', $args );

		if ( is_wp_error( $_menu ) ) {
			return $_menu;
		}

		/**
		 * Fires after a navigation menu is successfully created.
		 *
		 * @since 3.0.0
		 *
		 * @param int   $term_id   ID of the new menu.
		 * @param array $menu_data An array of menu data.
		 */
		do_action( 'wp_create_nav_menu', $_menu['term_id'], $menu_data );

		return (int) $_menu['term_id'];
	}

	if ( ! $_menu || ! isset( $_menu->term_id ) ) {
		return 0;
	}

	$menu_id = (int) $_menu->term_id;

	$update_response = wp_update_term( $menu_id, 'nav_menu', $args );

	if ( is_wp_error( $update_response ) ) {
		return $update_response;
	}

	$menu_id = (int) $update_response['term_id'];

	/**
	 * Fires after a navigation menu has been successfully updated.
	 *
	 * @since 3.0.0
	 *
	 * @param int   $menu_id   ID of the updated menu.
	 * @param array $menu_data An array of menu data.
	 */
	do_action( 'wp_update_nav_menu', $menu_id, $menu_data );
	return $menu_id;
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘wp_create_nav_menu’, int $term_id, array $menu_data )

Fires after a navigation menu is successfully created.

do_action( ‘wp_update_nav_menu’, int $menu_id, array $menu_data )

Fires after a navigation menu has been successfully updated.

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

Updates term based on arguments provided.
wp_insert_term()wp-includes/taxonomy.php

Adds a new term to the database.
get_term_by()wp-includes/taxonomy.php

Gets all term data from database by term field and data.
wp_get_nav_menu_object()wp-includes/nav-menu.php

Returns a navigation menu object.
__()wp-includes/l10n.php

Retrieves the translation of $text.
esc_html()wp-includes/formatting.php

Escaping for HTML blocks.
do_action()wp-includes/plugin.php

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

Checks whether the given variable is a WordPress Error.
WP_Error::__construct()wp-includes/class-wp-error.php

Initializes the error.

Show 5 moreShow less

Used by Description
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_REST_Menus_Controller::update_item()wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php

Updates a single term from a taxonomy.
WP_Customize_Nav_Menu_Setting::update()wp-includes/customize/class-wp-customize-nav-menu-setting.php

Create/update the nav_menu term for this setting.
wp_create_nav_menu()wp-includes/nav-menu.php

Creates a navigation menu.

Changelog

Version Description
3.0.0 Introduced.