云策 WordPress 开发者社区

函数文档

menu_page_url()

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

概述

menu_page_url() 函数用于根据注册的 slug 获取特定菜单页面的访问 URL。如果 slug 未正确注册，则返回空字符串。

关键要点

  • 函数接受两个参数：必需的 $menu_slug（菜单的唯一标识符）和可选的 $display（是否直接输出 URL，默认为 true）。
  • 返回值为字符串类型的菜单页面 URL，如果未找到则返回空字符串。
  • 内部使用全局变量 $_parent_pages 来检查父级菜单，并组合生成 admin.php 或带查询参数的 URL。
  • 通过 esc_url() 清理 URL 以确保安全性。
  • 在 AJAX 调用中可能无法工作，因为菜单未初始化，建议通过 wp_localize_script() 在客户端存储 URL。

代码示例

// 检查父菜单页面是否存在，并添加子菜单
$main_menu = menu_page_url('PARENT-PAGE-SLUG', false);

if ($main_menu) {
    // 父菜单存在，添加子菜单项
    add_submenu_page(
        'PARENT-PAGE-SLUG',
        esc_html__( 'Sub-Menu Page Title', 'myplugin' ),
        esc_html__( 'Sub-Menu Page', 'myplugin' ),
        'manage_options',
        'submenu-page-slug',
        'submenu_page_content_callback',
        2
    );
} else {
    // 无父菜单，创建新菜单
    add_menu_page(
        esc_html__( 'Parent Page Title', 'myplugin' ),
        esc_html__( 'Parent Page', 'myplugin' ),
        'manage_options',
        'parent-page-slug',
        'parent_menu_page_content_callback'
    );
}

注意事项

  • 确保菜单 slug 已通过 add_menu_page() 或 add_submenu_page() 正确注册，否则函数返回空 URL。
  • 在 AJAX 调用中，由于菜单未初始化，此函数可能返回空字符串，需考虑替代方案如客户端存储。
  • 函数自 WordPress 3.0.0 版本引入，相关函数包括 esc_url()、add_query_arg() 和 admin_url()。
📄 原文内容

Gets the URL to access a particular menu page based on the slug it was registered with.

Description

If the slug hasn’t been registered properly, no URL will be returned.

Parameters

$menu_slugstringrequired
The slug name to refer to this menu by (should be unique for this menu).
$displaybooloptional
Whether or not to display the URL.

Default:true

Return

string The menu page URL.

Source

function menu_page_url( $menu_slug, $display = true ) {
	global $_parent_pages;

	if ( isset( $_parent_pages[ $menu_slug ] ) ) {
		$parent_slug = $_parent_pages[ $menu_slug ];

		if ( $parent_slug && ! isset( $_parent_pages[ $parent_slug ] ) ) {
			$url = admin_url( add_query_arg( 'page', $menu_slug, $parent_slug ) );
		} else {
			$url = admin_url( 'admin.php?page=' . $menu_slug );
		}
	} else {
		$url = '';
	}

	$url = esc_url( $url );

	if ( $display ) {
		echo $url;
	}

	return $url;
}

View all references View on Trac View on GitHub

Uses Description
esc_url()wp-includes/formatting.php

Checks and cleans a URL.
add_query_arg()wp-includes/functions.php

Retrieves a modified URL query string.
admin_url()wp-includes/link-template.php

Retrieves the URL to the admin area for the current site.

Show 1 moreShow less

Used by Description
wp_enqueue_command_palette_assets()wp-includes/script-loader.php

Enqueues the assets required for the Command Palette.

Changelog

Version Description
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Tassawer Hussain


    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

    We can use this function to add a sub-menu under the existing parent menu.

    // check if parent admin page exist or not.
$main_menu = menu_page_url('PARENT-PAGE-SLUG', false);

if ($main_menu) {
    // The top menu exists, so add a sub-menu item.
    add_submenu_page(
        'PARENT-PAGE-SLUG',
        esc_html__( 'Sub-Menu Page Title', 'myplugin' ), // page Title
        esc_html__( 'Sub-Menu Page', 'myplugin' ), // menu link text
        'manage_options', // capability to access the page
        'submenu-page-slug', // page URL slug
        'submenu_page_content_callback', // callback function with content
        2 // priority
    );
} else {
    // No top menu with that slug, we can create it.
    add_menu_page(
        esc_html__( 'Parent Page Title', 'myplugin' ), // page Title
        esc_html__( 'Parent Page', 'myplugin' ), // menu link text
        'manage_options', // capability to access the page
        'parent-page-slug', // page URL slug
        'parent_menu_page_content_callback', // callback function with content
    );
}

  2. Skip to note 4 content


    David Brown


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

    Does not work in ajax calls because menus aren’t initialized; returns an empty string (at least for admin pages). See https://core.trac.wordpress.org/ticket/39003

    I was able to the store needed menu page URL client-side, in the localized JavaScript object I was creating anyway [wp_localize_script()].

    (Using WP version 6.6.2)