WordPress功能函数add_dashboard_page()，添加子菜单页到仪表板主菜单。

用法：

add_dashboard_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = ”, int $position = null )

描述：

该函数具有一种功能，用于确定菜单中是否包含某个页面。

用于处理页面输出的函数也必须检查用户是否具备所需的功能。

参数：

$page_title

(string) (必需) 选中菜单时要在页面标题标签中显示的文本。

$menu_title

(string) (必需) 要用于菜单的文本。

$capability

(string) (必需) 向用户显示该菜单所需的功能。

$menu_slug

(string) (必需) 用来引用这个菜单的蛞蝓名称(对于这个菜单应该是唯一的)。

$function

(callable) (可选) 用于输出此页面内容的函数。

默认值:“

$position

(int)(可选)该选项在菜单中应该出现的位置。

默认值:空

返回：

(string|false)结果页面的hook_suffix，如果用户不具备所需的能力则为false。

来源：

文件: wp-admin/includes/plugin.php

function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = ”, $position = null ) {

global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,

$_registered_pages, $_parent_pages;

$menu_slug = plugin_basename( $menu_slug );

$parent_slug = plugin_basename( $parent_slug );

if ( isset( $_wp_real_parent_file[ $parent_slug ] ) ) {

$parent_slug = $_wp_real_parent_file[ $parent_slug ];

}

if ( ! current_user_can( $capability ) ) {

$_wp_submenu_nopriv[ $parent_slug ][ $menu_slug ] = true;

return false;

}

/*

* If the parent doesn’t already have a submenu, add a link to the parent

* as the first item in the submenu. If the submenu file is the same as the

* parent file someone is trying to link back to the parent manually. In

* this case, don’t automatically add a link back to avoid duplication.

*/

if ( ! isset( $submenu[ $parent_slug ] ) && $menu_slug !== $parent_slug ) {

foreach ( (array) $menu as $parent_menu ) {

if ( $parent_menu[2] === $parent_slug && current_user_can( $parent_menu[1] ) ) {

$submenu[ $parent_slug ][] = array_slice( $parent_menu, 0, 4 );

}

}

}

$new_sub_menu = array( $menu_title, $capability, $menu_slug, $page_title );

if ( ! is_int( $position ) ) {

if ( null !== $position ) {

_doing_it_wrong(

__FUNCTION__,

sprintf(

/* translators: %s: add_submenu_page() */

__( ‘The seventh parameter passed to %s should be an integer representing menu position.’ ),

‘<code>add_submenu_page()</code>’

),

‘5.3.0’

);

}

$submenu[ $parent_slug ][] = $new_sub_menu;

} else {

// Append the submenu if the parent item is not present in the submenu,

// or if position is equal or higher than the number of items in the array.

if ( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) ) {

$submenu[ $parent_slug ][] = $new_sub_menu;

} else {

// Test for a negative position.

$position = max( $position, 0 );

if ( 0 === $position ) {

// For negative or `0` positions, prepend the submenu.

array_unshift( $submenu[ $parent_slug ], $new_sub_menu );

} else {

// Grab all of the items before the insertion point.

$before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true );

// Grab all of the items after the insertion point.

$after_items = array_slice( $submenu[ $parent_slug ], $position, null, true );

// Add the new item.

$before_items[] = $new_sub_menu;

// Merge the items.

$submenu[ $parent_slug ] = array_merge( $before_items, $after_items );

}

}

}

// Sort the parent array.

ksort( $submenu[ $parent_slug ] );

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

if ( ! empty( $function ) && ! empty( $hookname ) ) {

add_action( $hookname, $function );

}

$_registered_pages[ $hookname ] = true;

/*

* Backward-compatibility for plugins using add_management_page().

* See wp-admin/admin.php for redirect from edit.php to tools.php.

*/

if ( ‘tools.php’ === $parent_slug ) {

$_registered_pages[ get_plugin_page_hookname( $menu_slug, ‘edit.php’ ) ] = true;

}

// No parent as top level.

$_parent_pages[ $menu_slug ] = $parent_slug;

return $hookname;

}

更新日志：

用户贡献的笔记：

（由jakeparis贡献- 5年前）

• 仪表板: ‘index.php’
• 帖子: ‘edit.php’
• 媒体: ‘upload.php’
• 页面: ‘edit.php?post_type=page’
• 评论: ‘edit-comments.php’
• 自定义Post类型: ‘edit.php?post_type=your_post_type’
• 外观: ‘themes.php’
• 插件: ‘plugins.php’
• 用户: ‘users.php’
• 工具: ‘tools.php’
• 设置: ‘options-general.php’
• 网络设置: ‘settings.php’

（由Codex – 6年前贡献）

用add_menu_page()创建的内部菜单

如果您试图将子菜单页添加到通过add_menu_page()创建的菜单页，那么第一个子菜单页将是父add_menu_page()的副本。

如果在这个场景中你想要一个子菜单页面，你应该首先创建一个add_menu_page()的副本，然后添加你的add_submenu_page():

add_menu_page(‘My Custom Page’, ‘My Custom Page’, ‘manage_options’, ‘my-top-level-slug’);

add_submenu_page( ‘my-top-level-slug’, ‘My Custom Page’, ‘My Custom Page’,

‘manage_options’, ‘my-top-level-slug’);

add_submenu_page( ‘my-top-level-slug’, ‘My Custom Submenu Page’, ‘My Custom Submenu Page’,

‘manage_options’, ‘my-secondary-slug’);

（克里斯蒂娜·布拉斯特5年前提供）

将子菜单页添加到自定义文章类型

如果你想添加一个子菜单类型到一个自定义的文章类型，比如一个插件创建的自定义文章类型的参考页面，你可以使用$parent_slug参数，你可以在“所有的文章”视图的顶部看到这个文章类型。例如，对于自定义post类型“Book”，$parent_slug可以是’edit.php?post_type= Book ‘。

例子:

/**

* Adds a submenu page under a custom post type parent.

*/

function books_register_ref_page() {

add_submenu_page(

‘edit.php?post_type=book’,

__( ‘Books Shortcode Reference’, ‘textdomain’ ),

__( ‘Shortcode Reference’, ‘textdomain’ ),

‘manage_options’,

‘books-shortcode-ref’,

‘books_ref_page_callback’

);

}

/**

* Display callback for the submenu page.

*/

function books_ref_page_callback() {

?>

<div class=”wrap”>

<h2><?php _e( ‘Books Shortcode Reference’, ‘textdomain’ ); ?></h2>

<p><?php _e( ‘Helpful stuff here’, ‘textdomain’ ); ?></p>

</div>

<?php

}

（穆斯塔法·苏非4年前贡献）

php类的子菜单示例

/**

* Sub menu class

*

* @author Mostafa <mostafa.soufi@hotmail.com>

*/

class Sub_menu {

/**

* Autoload method

* @return void

*/

public function __construct() {

add_action( ‘admin_menu’, array(&$this, ‘register_sub_menu’) );

}

/**

* Register submenu

* @return void

*/

public function register_sub_menu() {

add_submenu_page(

‘options-general.php’, ‘Submenu title’, ‘Submenu title’, ‘manage_options’, ‘submenu-page’, array(&$this, ‘submenu_page_callback’)

);

}

/**

* Render submenu

* @return void

*/

public function submenu_page_callback() {

echo ‘<div class=”wrap”>’;

echo ‘<h2>Submenu title</h2>’;

echo ‘</div>’;

}

}

new Sub_menu();

（由Codex – 6年前贡献）

例子

add_action(‘admin_menu’, ‘wpdocs_register_my_custom_submenu_page’);

function wpdocs_register_my_custom_submenu_page() {

add_submenu_page(

‘tools.php’,

‘My Custom Submenu Page’,

‘My Custom Submenu Page’,

‘manage_options’,

‘my-custom-submenu-page’,

‘wpdocs_my_custom_submenu_page_callback’ );

}

function wpdocs_my_custom_submenu_page_callback() {

echo ‘<div class=”wrap”><div id=”icon-tools” class=”icon32″></div>’;

echo ‘<h2>My Custom Submenu Page</h2>’;

echo ‘</div>’;

}

要从它所属的顶级菜单项隐藏子菜单链接，你可以这样做

add_action(‘admin_menu’, ‘wpdocs_register_my_custom_submenu_page’);

function wpdocs_register_my_custom_submenu_page() {

add_submenu_page(

null, //or ‘options.php’

‘My Custom Submenu Page’,

‘My Custom Submenu Page’,

‘manage_options’,

‘my-custom-submenu-page’,

‘my_custom_submenu_page_callback’,

);

}

（由LogixTree在4年前贡献）

在处理这些类时，您可以通过遵循确保可调用对象是静态函数来添加_submenu_page。

add_submenu_page( ‘admin_menu’, ‘Custom Menu’, ‘My Custom Menu’, ‘manage_options’, ‘my-custom-menu’, __CLASS__ .’::menu_page_output’ );

public menu_page_output() {

//Menu Page output code

}

（由ILOVEWP贡献- 4年前）

对于其他故障排除此函数意外问题的人，请注意最后一个参数，特别是$函数，它必须是一个字符串，函数名，而不是对函数本身的调用。业余的错误，我知道，但有时你只是犯了最简单的错误。

缺点:

add_menu_page(‘My Custom Page’, ‘My Custom Page’, ‘manage_options’, ‘my-top-level-slug’, my-output-function());

优势：

add_menu_page(‘My Custom Page’, ‘My Custom Page’, ‘manage_options’, ‘my-top-level-slug’, ‘my-output-function’);

（由tripflex提供- 3年前）

为了进一步说明添加一个页面而不显示在菜单/子菜单中，使用以下代码:

add_action(‘admin_menu’, ‘wpdocs_register_my_custom_submenu_page’);

function wpdocs_register_my_custom_submenu_page() {

add_submenu_page(

‘options.php’,

‘My Custom Submenu Page’,

‘My Custom Submenu Page’,

‘manage_options’,

‘my-custom-submenu-page’,

‘my_custom_submenu_page_callback’,

);

}

然后您将通过以下URL访问此页面:/wp-admin/options.php?page=my-custom-submenu-page

（由isMike()贡献- 11个月前）

如果在类中工作，add_submenu_page的“function”参数应该是一个数组，数组中的第一个值是类的实例，而数组中的第二个值是对象中的一个方法(以字符串的形式给出)。

在下面的例子

Class WPDocs_AdminPage

{

private $_plugin_name;

private $_version;

public function __construct( $plugin_name, $version )

{

$this->_plugin_name = $plugin_name;

$this->_version = $version;

}

public function wpdocs_create_menu_and_submenu_page()

{

add_menu_page(

‘PAGE TITLE’, ‘MENU TITLE’, ‘CAPABILITY’, ‘menu_slug’,

array( $this, ‘wpdocs_method_name_in_the_class’ ), ‘icon_url’, ‘POSITION’

);

add_submenu_page(

‘parent_slug’, ‘PAGE TITLE’, ‘MENU TITLE’, ‘CAPABILITY’, ‘menu_slug’,

array( $this, ‘wpdocs_method_name_in_the_class’ )

);

}

}

$admin_page = new WPDocs_AdminPage;

add_action( ‘admin_menu’, array( $admin_page, ‘wpdocs_create_menu_and_submenu_page’ ) );

（由isabel104贡献- 4个月前）

关于上面“更多信息”部分的第一个提示，你也可能会遇到“对不起，您不允许访问此页面。”消息，即使您已正确地钩入admin_menu钩子。如果所有这些都为真，则会出现此错误信息:

• 父页面是使用add_menu_page添加的自定义页面
• 父页面是在另一个插件中创建的，而不是创建子菜单页面的同一个插件
• 您没有为add_submenu_page调用向admin_menu钩子添加较低的优先级，因此子菜单页可能在父页面之前被触发，从而导致错误。

解决方案:向创建子菜单页面的操作添加较低的优先级，如99。例如:

add_action( ‘admin_menu’, ‘wpdocs_register_my_custom_submenu_page’, 99 );

（rtpHarry于6个月前贡献）

如果你想把你的自定义子页面的url如下:

https://www.example.com/wp-admin/admin.php?page=custom-settings

那你应该使用父弹头的自定义设置。

在我的用例中，我想把一个自定义分类法放在一个ACF选项页面下，我使用了这个:

add_submenu_page(

‘custom-settings’,

‘Product Filter By Ambient Noise’,

‘Product Filter By Ambient Noise’,

‘manage_options’,

‘edit-tags.php?taxonomy=product-filter-ambient-noise’

);

（由猎魔人贡献- 6年前）

人们喜欢“工具”。php ‘可以在旧文档https://codex.wordpress.org/Function_Reference/add_submenu_page#Parameters中找到