管理菜单

管理菜单
顶级菜单
子菜单

管理菜单

管理菜单是 WordPress 管理中显示的界面。它们允许您为插件添加选项页面。

有关管理导航菜单的信息，请参阅主题开发人员手册的导航菜单一章。

顶级菜单和子菜单

顶级菜单沿着 WordPress 管理的左侧呈现。每个菜单可能包含一组子菜单。

在顶级菜单和子菜单之间做出决定时，请仔细考虑插件的需求以及最终用户的需求。

警报：我们建议具有单个选项页面的开发人员将其作为子菜单添加到现有的顶级菜单之一；例如设置或工具。

顶级菜单

添加顶级菜单

要将新的顶级菜单添加到 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注册的选项。

笔记：我们建议使用wrap.

第二步是注册我们的 WPOorg 菜单。注册需要在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_slugnull $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()。该函数会自动转义 URL 并默认回显它，因此您可以直接在标签内使用它<form>：

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

处理表格

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

add_menu_page返回一个$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验证
验证
消毒

子菜单

添加子菜单

要向 WordPress 管理添加新的子菜单，请使用该add_submenu_page()功能。

add_submenu_page(
	string $parent_slug,
	string $page_title,
	string $menu_title,
	string $capability,
	string $menu_slug,
	callable $function = ''
);

例子

假设我们要向“工具”顶级菜单添加一个子菜单“WPOrg Options”。

第一步是创建一个输出 HTML 的函数。在此函数中，我们将执行必要的安全检查并呈现我们使用Settings API注册的选项。

我们建议使用wrap.

function wporg_options_page_html() {
	// check user capabilities
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}
	?>

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

function wporg_options_page()
{
	add_submenu_page(
		'tools.php',
		'WPOrg Options',
		'WPOrg Options',
		'manage_options',
		'wporg',
		'wporg_options_page_html'
	);
}
add_action('admin_menu', 'wporg_options_page');

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

预定义子菜单

$parent_slug如果我们有帮助函数来定义WordPress 内置顶级菜单并使我们免于通过源代码手动搜索它，那不是很好吗？

下面是父 slugs 及其辅助函数的列表：

add_dashboard_page() –index.php
add_posts_page() –edit.php
add_media_page() –upload.php
add_pages_page() –edit.php?post_type=page
add_comments_page() –edit-comments.php
add_theme_page() –themes.php
add_plugins_page() –plugins.php
add_users_page() –users.php
add_management_page() –tools.php
add_options_page() –options-general.php
add_options_page() –settings.php
add_links_page() – link-manager.php– 从 WP 3.5+ 开始需要插件
自定义帖子类型 –edit.php?post_type=wporg_post_type
网络管理员 –settings.php

删除子菜单

删除子菜单的过程与删除顶级菜单的过程完全相同。

提交表格

在子菜单中处理表单提交的过程与在顶级菜单中提交表单完全相同。

add_submenu_page()与预定义子菜单（add_dashboard_page、add_posts_page等）的所有函数一起将返回 a $hookname，您可以将其用作的第一个参数，add_action以便处理自定义页面中表单的提交：

function wporg_options_page() {
	$hookname = add_submenu_page(
		'tools.php',
		'WPOrg Options',
		'WPOrg Options',
		'manage_options',
		'wporg',
		'wporg_options_page_html'
	);

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

add_action('admin_menu', 'wporg_options_page');

一如既往，不要忘记检查表单是否正在提交，进行 CSRF 验证、验证和清理。