Question

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

在侧边栏，添加一个顶级的菜单。

---

description

这个函数需要一个功能，用于决定菜单中是否包含页面。连接到处理页面输出的函数必须检查用户是否具有所需的能力。

---

参数

$page_title

(string)
(Required)
当菜单被选中时将显示在页面标题标签中的文本。

$menu_title

(string)
(Required)
用于菜单的文本。

$capability

(string)
(Required)
将此菜单显示给用户所需的功能。

$menu_slug

(string)
(Required)
要引用此菜单的URL地址

$function

(callable)
(Optional)
要为该页输出内容的函数。Default value: ''

$icon_url

(string)
(Optional)
此菜单使用的图标的URL。
* 通过base64编码数据的URI使用SVG技术，将彩色的色彩搭配方案。这应该从 'data:image/svg+xml;base64,'.
* 经过一个dashicons辅助类的名称使用字体图标，例如 'dashicons-chart-pie'.
* 设置为 none，div.wp-menu-image 所以图标可以通过增加CSS。Default value: ''

$position

(int)
(Optional)
菜单顺序中的位置应该出现。Default value: null

---

返回值

(string) 返回页面的 hook_suffix。

---

源代码

File: wp-admin/includes/plugin.php

function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = null ) {
	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;

	$menu_slug = plugin_basename( $menu_slug );

	$admin_page_hooks[$menu_slug] = sanitize_title( $menu_title );

	$hookname = get_plugin_page_hookname( $menu_slug, '' );

	if ( !empty( $function ) && !empty( $hookname ) && current_user_can( $capability ) )
		add_action( $hookname, $function );

	if ( empty($icon_url) ) {
		$icon_url = 'dashicons-admin-generic';
		$icon_class = 'menu-icon-generic ';
	} else {
		$icon_url = set_url_scheme( $icon_url );
		$icon_class = '';
	}

	$new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url );

	if ( null === $position ) {
		$menu[] = $new_menu;
	} elseif ( isset( $menu[ "$position" ] ) ) {
	 	$position = $position + substr( base_convert( md5( $menu_slug . $menu_title ), 16, 10 ) , -5 ) * 0.00001;
		$menu[ "$position" ] = $new_menu;
	} else {
		$menu[ $position ] = $new_menu;
	}

	$_registered_pages[$hookname] = true;

	// No parent as top level
	$_parent_pages[$menu_slug] = false;

	return $hookname;
}

---

更多信息

• Important Note: Since WordPress 4.4, you do not need to worry about making the position number unique to avoid conflicts. See trac ticket
• If you’re running into the “You do not have sufficient permissions to access this page” error, then you’ve hooked too early. The hook you should use is admin_menu.

• If you only want to move existing admin menu items to different positions, you can use the admin_menu hook to unset menu items from their current positions in the global $menu and $submenu variables (which are arrays), and reset them elsewhere in the array.

• This function takes a ‘capability’ (see Roles and Capabilities) which will be used to determine whether or not a page is included in the menu. The function which is hooked in to handle the output of the page must check that the user has the required ‘capability’ as well.

• If you are using the Settings API to save data, and need the user to be other than the administrator, will need to modify the permissions via the hook option_page_capability_{$option_group}, where $option_group is the same as option_group in register_setting() . Check out the Settings API.

允许编辑器保存数据的示例：

// Register settings using the Settings API 
function wpdocs_register_my_setting() {
	register_setting( 'my-options-group', 'my-option-name', 'intval' ); 
} 
add_action( 'admin_init', 'wpdocs_register_my_setting' );

// Modify capability
function wpdocs_my_page_capability( $capability ) {
	return 'edit_others_posts';
}
add_filter( 'option_page_capability_my-options-group', 'wpdocs_my_page_capability' );

菜单结构

默认菜单结构的底部

• 2 – Dashboard
• 4 – Separator
• 5 – Posts
• 10 – Media
• 15 – Links
• 20 – Pages
• 25 – Comments
• 59 – Separator
• 60 – Appearance
• 65 – Plugins
• 70 – Users
• 75 – Tools
• 80 – Settings
• 99 – Separator

对于网络管理菜单，值是不同的：

• 2 – Dashboard
• 4 – Separator
• 5 – Sites
• 10 – Users
• 15 – Themes
• 20 – Plugins
• 25 – Settings
• 30 – Updates
• 99 – Separator

---

相关函数

Uses

• • wp-admin/includes/plugin.php:get_plugin_page_hookname()
  • wp-includes/capabilities.php:current_user_can()
  • wp-includes/formatting.php:sanitize_title()
  • wp-includes/link-template.php:set_url_scheme()
  • wp-includes/plugin.php:plugin_basename()
  • wp-includes/plugin.php:add_action()

---

Used By

• wp-admin/includes/deprecated.php:add_object_page()
• wp-admin/includes/deprecated.php:add_utility_page()

---

使用举例

添加一个自定义菜单项到WordPress管理菜单，对于具有管理员功能的用户：

Method 1:

/**
 * Register a custom menu page.
 */
function wpdocs_register_my_custom_menu_page() {
	add_menu_page(
		__( 'Custom Menu Title', 'textdomain' ),
		'custom menu',
		'manage_options',
		'myplugin/myplugin-admin.php',
		'',
		plugins_url( 'myplugin/images/icon.png' ),
		6
	);
}
add_action( 'admin_menu', 'wpdocs_register_my_custom_menu_page' );

使用这种方法，页面生成代码应该位于 myplugin/myplugin-admin.php：

<?php esc_html_e( 'Admin Page Test', 'textdomain' ); ?>

Method 2:

/**
 * Register a custom menu page.
 */
function wpdocs_register_my_custom_menu_page(){
	add_menu_page( 
		__( 'Custom Menu Title', 'textdomain' ),
		'custom menu',
		'manage_options',
		'custompage',
		'my_custom_menu_page',
		plugins_url( 'myplugin/images/icon.png' ),
		6
	); 
}
add_action( 'admin_menu', 'wpdocs_register_my_custom_menu_page' );

/**
 * Display a custom menu page
 */
function my_custom_menu_page(){
	esc_html_e( 'Admin Page Test', 'textdomain' );	
}

/**
 * Create admin Page to list unsubscribed emails.
 */
 // Hook for adding admin menus
 add_action('admin_menu', 'wpdocs_unsub_add_pages');

 // action function for above hook

/**
 * Adds a new top-level page to the administration menu.
 */
function wpdocs_unsub_add_pages() {
     add_menu_page(
	 	__( 'Unsub List', 'textdomain' ),
		__( 'Unsub Emails','textdomain' ),
		'manage_options',
		'wpdocs-unsub-email-list',
		'wpdocs_unsub_page_callback',
		''
	);
}

/**
 * Disply callback for the Unsub page.
 */
 function wpdocs_unsub_page_callback() {
     echo 'Unsubscribe Email List';
 }

实际上在我看来，这个  $position 有点不好，如果你设置80，可能会覆盖掉整个 WordPress 的菜单，我还没有测试过这个，但是我猜插件/主题设置的菜单也是这样。

好的方法是你可以使用带有小数的优先级，例如你可以使用“80.321”让你的菜单显示在设置下面。注意，不支持浮点值，必须是引号中的字符串，这里甚至没有记录。

加上Dashicons的网页菜单。更多dashicons这里请查阅这里：https://developer.wordpress.org/resource/dashicons/#menu

add_action( 'admin_menu', 'register_my_custom_menu_page' );
function register_my_custom_menu_page() {
  // add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );
  add_menu_page( 'Custom Menu Page Title', 'Custom Menu Page', 'manage_options', 'custom.php', '', 'dashicons-welcome-widgets-menus', 90 );
}

// For those who are object orientated. Add a class 
// function as the menu callback and setup the 
// menus automatically. 

// Exit if accessed directly
if ( !defined( 'ABSPATH' ) ) exit;

class MyMenuSetterUpper {

    private static $instance;

    /**
     * Main Instance
     *
     * @staticvar 	array 	$instance
     * @return 		The one true instance
     */
    public static function instance() {
         if ( ! isset( self::$instance ) ) {
             self::$instance = new self;
	     self::$instance->addMyAdminMenu();
	}

        return self::$instance;
    }

    public function addMyAdminMenu() {
         
         add_menu_page(
            'My Page Title',
            'My Page',
            'read',
            'my-menu-page-slug',
            array(
                $this,
                'myAdminPage'
            ),
            'to/icon/file.svg',
            '2.1'
        );
    }

    public function myAdminPage() {
         // Echo the html here...
    }

}
// Call the class and add the menus automatically. 
$MyMenuSetterUpper = MyMenuSetterUpper::instance();