顶级菜单

添加顶级菜单

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

<?php
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注册的选项。

<?php
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动作钩子期间进行。

<?php
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

可移植代码的最佳实践是创建一个回调requires/includes您的PHP文件。

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

<?php
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()函数。

<?php
remove_menu_page(
    string $menu_slug
);
?>

 

实例

假设我们想删除“工具”菜单。

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

确保菜单已注册到admin_menu钩子，然后再尝试删除，为add_action()指定更高的优先级。

 

提交表单

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

1. 使用页面的URL作为表单的action属性。
2. 添加一个带有slug的钩子，由add_menu_page返回。

 

表单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"动作。您可以使用它来分配一个函数，该函数可以处理表单。

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

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进行编程，但请记住，您必须手动执行所有必要的检查，包括：

1. 是否正在提交表单（'POST' === $_SERVER['REQUEST_METHOD']）。
2. CSRF验证
3. 数据验证
4. 数据清理