顶级菜单

最后更新：2026-10-07 14:59:14

添加顶级菜单

要向 WordPress 管理后台添加一个新的顶级菜单，请使用 add_menu_page() 函数。

add_menu_page(
    string $page_title,
    string $menu_title,
    string $capability,
    string $menu_slug,
    callable $function = '',
    string $icon_url = '',
    int $position = null
);

示例

假设我们要添加一个名为“WPOrg”的新顶级菜单。

第一步是创建一个用于输出 HTML 的函数。在该函数中，我们将执行必要的安全检查，并使用设置 API 渲染已注册的选项。

我们建议使用一个类为 wrap 的 <div> 来包裹您的 HTML。

function wporg_options_page_html() {
    ?>
    <div class="wrap">
      <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
      <form action="options.php" method="post">
        <?php
        // 为已注册的设置 "wporg_options" 输出安全字段
        settings_fields( 'wporg_options' );
        // 输出设置部分及其字段
        // (部分注册给 "wporg"，每个字段注册到特定部分)
        do_settings_sections( 'wporg' );
        // 输出保存设置按钮
        submit_button( __( 'Save Settings', 'textdomain' ) );
        ?>
      </form>
    </div>
    <?php
}

第二步是注册我们的 WPOrg 菜单。注册需要在 admin_menu 操作钩子期间进行。

add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
    add_menu_page(
        'WPOrg',
        'WPOrg Options',
        'manage_options',
        'wporg',
        'wporg_options_page_html',
        plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
        20
    );
}

有关参数列表及每个参数的作用，请参阅参考中的 add_menu_page()。

使用 PHP 文件处理 HTML

对于可移植代码的最佳做法是创建一个回调函数，该函数需要/包含您的 PHP 文件。

为了完整性并帮助您理解旧版代码，我们将展示另一种方法：将 PHP 文件路径 作为 $menu_slug 参数传递，并将 null $function 参数。

add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
    add_menu_page(
        'WPOrg',
        'WPOrg Options',
        'manage_options',
        plugin_dir_path(__FILE__) . 'admin/view.php',
        null,
        plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
        20
    );
}

删除顶级菜单

要从 WordPress 管理后台删除已注册的菜单，请使用 remove_menu_page() 函数。

remove_menu_page(
    string $menu_slug
);

删除菜单不会阻止用户直接访问它们。
这绝不应用作限制用户能力的方法。

示例

假设我们要从...中删除“工具”菜单。

add_action( 'admin_menu', 'wporg_remove_options_page', 99 );
function wporg_remove_options_page() {
    remove_menu_page( 'tools.php' );
}

在尝试删除之前，请确保菜单已通过 admin_menu 钩子注册，并为 add_action() 指定较高的优先级数字。

提交表单

要处理选项页面上表单的提交，您需要两件事：

使用页面的 URL 作为表单的 action 属性。
添加一个钩子，其标识符由 add_menu_page 返回。

如果您在后端手动创建表单，则只需遵循这些步骤。设置 API 是执行此操作的首选方法。

表单 action 属性

使用选项页的 $menu_slug 参数作为 menu_page_url() 的第一个参数。该函数默认会自动转义 URL 并回显，因此您可以直接在 <form> 标签中使用它：

<form action="<?php menu_page_url( 'wporg' ) ?>" method="post">

处理表单

您在添加页面时指定的 $function 仅在需要显示页面时才会被调用，这使得它在需要向浏览器发送标头（例如重定向）时不合适。

add_menu_page 返回一个 $hookname，WordPress 会在任何 HTML 输出之前触发 "load-$hookname" 操作。您可以使用此功能来分配一个函数，该函数可以处理表单。

"load-$hookname" 将在每次显示选项页面之前执行，即使表单未被提交。

考虑到返回参数和操作，上面的示例将如下所示：

add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
	$hookname = add_menu_page(
		'WPOrg',
		'WPOrg Options',
		'manage_options',
		'wporg',
		'wporg_options_page_html',
		plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
		20
	);

	add_action( 'load-' . $hookname, 'wporg_options_page_submit' );
}

您可以根据需要编程 wporg_options_page_submit，但请记住您必须手动执行所有必要的检查，包括：

表单是否正在提交（'POST' === $_SERVER['REQUEST_METHOD']）。
CSRF 验证
验证
清理