顶级菜单

添加顶级菜单

要向 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 的函数。在此函数中，我们将执行必要的安全检查并呈现我们使用Settings API注册的选项。

笔记：

我们建议使用<div>类包装您的 HTML wrap。

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
        // output security fields for the registered setting "wporg_options"
        settings_fields( 'wporg_options' );
        // output setting sections and their fields
        // (sections are registered for "wporg", each field is registered to a specific section)
        do_settings_sections( 'wporg' );
        // output save settings button
        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 文件的回调。

为了完整性和帮助您理解遗留代码，我们将展示另一种方式：将 aPHP file path作为$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表单的属性。
添加一个带 slug 的钩子，由返回add_menu_page。

笔记：
如果您在后端手动创建表单，则只需执行这些步骤。设置API是执行此操作的推荐方法。

表单动作属性

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

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

处理表格

您$function在添加页面时指定的只会在显示页面时调用，如果您需要将标头（例如重定向）发送回浏览器，这将不合适。

add_menu_page返回 a $hookname，并且 WordPress"load-$hookname"在任何 HTML 输出之前触发操作。您可以使用它来分配一个可以处理表单的函数。

笔记：
"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验证
验证
消毒