函数文档

wp_get_nav_menu_to_edit()

💡 云策文档标注

概述

wp_get_nav_menu_to_edit() 函数用于获取格式化后的导航菜单以供编辑。它接受菜单 ID 参数,返回编辑界面所需的 HTML 字符串、WP_Error 对象或 null。

关键要点

  • 参数 $menu_id 为可选整数,默认值为 0,用于指定要格式化的菜单 ID。
  • 返回值类型为 string|WP_Error|null:成功时返回格式化后的菜单 HTML 字符串;失败时返回 WP_Error 对象;若 $menu_id 未提供或菜单不存在则返回 null。
  • 函数内部调用 wp_get_nav_menu_object() 获取菜单对象,并使用 wp_get_nav_menu_items() 获取菜单项。
  • 通过 apply_filters('wp_edit_nav_menu_walker', 'Walker_Nav_Menu_Edit', $menu_id) 钩子可自定义 Walker 类,默认使用 Walker_Nav_Menu_Edit。
  • 函数会检查菜单项的状态,如存在草稿或无效项,会添加相应的管理员通知。
  • 使用 walk_nav_menu_tree() 生成菜单项的 HTML 列表结构。

代码示例

function wp_get_nav_menu_to_edit( $menu_id = 0 ) {
    $menu = wp_get_nav_menu_object( $menu_id );

    if ( is_nav_menu( $menu ) ) {
        $menu_items = wp_get_nav_menu_items( $menu->term_id, array( 'post_status' => 'any' ) );
        $result = ''; // 初始化结果字符串
        // ... 处理菜单项和生成 HTML 的逻辑
        return $result;
    } elseif ( is_wp_error( $menu ) ) {
        return $menu;
    }

    return null;
}

注意事项

  • 确保 $menu_id 参数有效,否则可能返回 null 或错误。
  • 自定义 Walker 类时需通过 wp_edit_nav_menu_walker 过滤器,并确保类存在,否则会返回 WP_Error。
  • 函数处理菜单项时包括草稿和无效项,需注意界面提示。

📄 原文内容

Returns the menu formatted to edit.

Parameters

$menu_idintoptional
The ID of the menu to format. Default 0.

Return

string|WP_Error|null The menu formatted to edit or error object on failure.
Null if the $menu_id parameter is not supplied or the term does not exist.

Source

function wp_get_nav_menu_to_edit( $menu_id = 0 ) {
	$menu = wp_get_nav_menu_object( $menu_id );

	// If the menu exists, get its items.
	if ( is_nav_menu( $menu ) ) {
		$menu_items = wp_get_nav_menu_items( $menu->term_id, array( 'post_status' => 'any' ) );
		$result     = '<div id="menu-instructions" class="post-body-plain';
		$result    .= ( ! empty( $menu_items ) ) ? ' menu-instructions-inactive">' : '">';
		$result    .= '<p>' . __( 'Add menu items from the column on the left.' ) . '</p>';
		$result    .= '</div>';

		if ( empty( $menu_items ) ) {
			return $result . ' <ul class="menu" id="menu-to-edit"> </ul>';
		}

		/**
		 * Filters the Walker class used when adding nav menu items.
		 *
		 * @since 3.0.0
		 *
		 * @param string $class   The walker class to use. Default 'Walker_Nav_Menu_Edit'.
		 * @param int    $menu_id ID of the menu being rendered.
		 */
		$walker_class_name = apply_filters( 'wp_edit_nav_menu_walker', 'Walker_Nav_Menu_Edit', $menu_id );

		if ( class_exists( $walker_class_name ) ) {
			$walker = new $walker_class_name();
		} else {
			return new WP_Error(
				'menu_walker_not_exist',
				sprintf(
					/* translators: %s: Walker class name. */
					__( 'The Walker class named %s does not exist.' ),
					'<strong>' . $walker_class_name . '</strong>'
				)
			);
		}

		$some_pending_menu_items = false;
		$some_invalid_menu_items = false;

		foreach ( (array) $menu_items as $menu_item ) {
			if ( isset( $menu_item->post_status ) && 'draft' === $menu_item->post_status ) {
				$some_pending_menu_items = true;
			}
			if ( ! empty( $menu_item->_invalid ) ) {
				$some_invalid_menu_items = true;
			}
		}

		if ( $some_pending_menu_items ) {
			$message     = __( 'Click Save Menu to make pending menu items public.' );
			$notice_args = array(
				'type'               => 'info',
				'additional_classes' => array( 'notice-alt', 'inline' ),
			);
			$result     .= wp_get_admin_notice( $message, $notice_args );
		}

		if ( $some_invalid_menu_items ) {
			$message     = __( 'There are some invalid menu items. Please check or delete them.' );
			$notice_args = array(
				'type'               => 'error',
				'additional_classes' => array( 'notice-alt', 'inline' ),
			);
			$result     .= wp_get_admin_notice( $message, $notice_args );
		}

		$result .= '<ul class="menu" id="menu-to-edit"> ';
		$result .= walk_nav_menu_tree(
			array_map( 'wp_setup_nav_menu_item', $menu_items ),
			0,
			(object) array( 'walker' => $walker )
		);
		$result .= ' </ul> ';

		return $result;
	} elseif ( is_wp_error( $menu ) ) {
		return $menu;
	}

	return null;
}

Hooks

apply_filters( ‘wp_edit_nav_menu_walker’, string $class, int $menu_id )

Filters the Walker class used when adding nav menu items.

Changelog

Version Description
3.0.0 Introduced.