「関数リファレンス/add menu page」の版間の差分

2018年9月26日 (水) 00:48時点における最新版

説明

トップレベルのメニューページを追加します。

具体的には、管理者メニューのサイドバーに新しいトップレベルのメニューのセクションを作成します。リンクされたメニューのページが要求されたとき、ページの内容を出力するための関数をコールバックしますが、指定された関数をそれ専用のフック（アクション）に登録します。そしてフック名を返します。

使い方

<?php add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position ); ?>

パラメータ

$page_title

（文字列） （必須） メニューが選択されたとき、ページのタイトルタグに表示されるテキスト。

初期値： なし

$menu_title

（文字列） （必須） メニューとして表示されるテキスト

初期値： なし

$capability

（文字列） （必須） メニューを表示するために必要な権限。注:ユーザーレベルは非推奨ですので使用しないでください。

初期値： なし

$menu_slug

（文字列） （必須） メニューのスラッグ名。一意であり、小文字の英数字、ダッシュ、下線のみを含む必要があります。これは sanitize_key() /en と互換の文字セットです。

初期値： なし

バージョン 3.0以前はファイル（またはハンドル）パラメータと呼ばれていました。

$function パラメータを省略した場合、$menu_slug はメニューページを表示する PHP ファイルのパス名またはハンドルである必要があります。

$function

（文字列） （オプション） メニューページを表示する際に実行される関数

初期値： ''

$function パラメータを省略した場合、WordPress はインクルードされる PHP ファイルが関数を呼び出すことなく管理画面を生成することを前提とします。ほとんどのプラグイン作者はプラグインファイル内の関数でページを生成しています。

このパラメータを指定した場合、$menu_slug パラメータは任意の文字列を使用できます。これにより ?page=my-super-plugin/admin-options.php の代わりに ?page=my_super_plugin_page のような URL を実現できます。

関数は次のいずれかの方法で参照する必要があります:

1. プラグイン内でクラスのメンバとして定義した場合は、array( $this, '関数名' )
2. 他の場合は、関数名だけを記述すれば充分です。

$icon_url

（文字列） （オプション） メニューのアイコンを示す URL

初期値： ''

• カスタムイメージを使用する場合、plugin_dir_url( __FILE__ ) 関数を使用して取得したプラグインディレクトリにイメージファイル名を追加し、指定することができます。アイコンは20×20ピクセル以下でなければなりません。
• (WP 3.8+) 'dashicons-...' の場合、https://developer.wordpress.org/resource/dashicons/ にまとめられている「ダッシュアイコン」が表示されます。例えばデフォルトの「歯車」のシンボルは 'dashicons-admin-generic' と明示的に指定できます。
• (WP 3.8+) 'data:image/svg+xml;base64,...' の場合、CSS background として、指定された SVG データ画像が使用されます。
• 'none' (以前は 'div')の場合、アイコンは、CSS でスタイル可能な空白の div と入れ替えられます。
• '' (デフォルト)の場合、歯車ダッシュアイコンが表示されます。 (そして、menu-icon-generic がリンクの CSS クラスに追加されます。)

$position

（整数） （オプション） メニューが表示される位置。省略時はメニュー構造の最下部に表示されます。大きい数値ほど下に表示されます。

注意: 2つのメニューが同じ位置を指定している場合、片方のみ表示され上書きされる可能性があります。衝突のリスクは整数値でなく小数値を使用することで回避することができます。

例： 63の代わりに63.3（コード内ではクォートを使用。例えば '63.3'）

初期値： メニュー構造の最下部

• 2 - ダッシュボード
• 4 - （セパレータ）
• 5 - 投稿
• 10 - メディア
• 15 - リンク
• 20 - 固定ページ
• 25 - コメント
• 59 - （セパレータ）
• 60 - 外観（テーマ）
• 65 - プラグイン
• 70 - ユーザー
• 75 - ツール
• 80 - 設定
• 99 - （セパレータ）

ネットワーク管理者メニューでは、値が異なります:

• 2 - ダッシュボード
• 4 - （セパレータ）
• 5 - 参加サイト
• 10 - ユーザー
• 15 - テーマ
• 20 - プラグイン
• 25 - 設定
• 30 - 更新
• 99 - （セパレータ）

戻り値

文字列 

メニューページを出力する関数をコールバックするためのフック（アクション）名。フック名はメニュー自体と共に、グローバルな $menu 配列へ保存されます。

用例

管理者権限ユーザー向けに、WordPress の管理メニューにカスタムメニュー項目を追加します。

例 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' ); ?>

例 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' );  
}

参考

• 重要: WordPress 4.4 から、衝突を避けるために $position をユニークに保つ心配は不要になりました。詳しくは #23316 を見てください。

• もし「このページにアクセスする権限がありません」エラーに出くわした場合、フックするのが早すぎるということです。使用すべきフックは admin_menu です。

• もし既存の管理者メニューのアイテムを別の場所に移動させたいだけの場合、admin_menu フックを使ってグローバルな $menu と $submenu 変数（両方とも配列）内の現在の位置からメニューのアイテムを取り除き、配列の他の場所に設置することができます。

• この関数は「権限」(Roles and Capabilities 参照)を使用して、メニューにページが含まれるかどうかを決定しています。同様に、ページの出力を取り扱うためにフックされた関数も、要求される「権限」をユーザーが持っていることを検証しなければなりません。

• Settings API を使ってデータを保存していて、ユーザーが管理者以外である必要がある場合、$option_group が register_setting() 内の $option_group と同じである option_page_capability_{$option_group} フックを通じて権限を修正する必要があります。Settings API を参照してください。.

編集者にデータを保存させる例:

// Settings APIを使って設定を登録
function register_my_setting() {
	register_setting( 'my-options-group', 'my-option-name', 'intval' ); 
} 
add_action( 'admin_init', 'register_my_setting' );

// 権限の修正
function my_page_capability( $capability ) {
	return 'edit_others_posts';
}
add_filter( 'option_page_capability_my-options-group', 'my_page_capability' );

変更履歴

ソースファイル

add_menu_page()は wp-admin/includes/plugin.php にあります。

外部リソース

• http://log.noiretaya.com/206 http://log.noiretaya.com/206 http://log.noiretaya.com/206 WordPress 管理画面にメニュー項目を追加する
• http://gatespace.jp/2013/12/19/wordpress-3-8-dashboard-icon/WordPress 3.8 テーマやプラグインでダッシュボードメニューのアイコンを設定する方法

関連項目

管理メニューの追加

管理メニュー: add_menu_page(), remove_menu_page(), add_submenu_page() /en, remove_submenu_page() /en, add_dashboard_page() /en, add_posts_page() /en, add_media_page() /en, add_links_page() /en, add_pages_page() /en, add_comments_page() /en, add_theme_page() /en, add_plugins_page() /en, add_users_page() /en, add_management_page() /en, add_options_page()

最新英語版: Reference / Functions / add_menu_page()