WooCommerce 管理ページの操作

Posted2024年9月25日

Updated2024年9月25日

Byadmin_artws

このページは WooCommerce の管理画面にサブメニューを追加して、拡張プラグインの設定画面などを作るのに役立つ記事です。以下の日本語訳になります。

PHP で動くページを WooCommerce Admin に接続する

既存の PHP ベースの管理ページをページコントローラーに登録するには、wc_admin_connect_page() 関数を使用します。例:

wc_admin_connect_page(
    array(
        'id'        => 'woocommerce-settings',
        'screen_id' => 'woocommerce_page_wc-settings-general',
        'title'     => array('Settings', 'General'),
        'path'      => add_query_arg( 'page', 'wc-settings', 'admin.php' ),
    )
);

wc_admin_connect_page() 関数は最大 5 つの引数を取りますが、そのうち 2 つはオプションです。

id – 必須 — コントローラでページを識別します。
parent – オプション — この値は、ページが親の子であることを示し (親[parent]の ID を使用)、パンくずリストの生成に使用されます。
screen_id – 必須 — PageController::get_current_screen_id() に対応します。現在のページを特定するために使用されます (以下の注記を参照)。
title – 必須 — ページのタイトルに対応し、パンくずリストの作成に使用されます。ここでは、パンくずリストの文字列または配列を指定できます。
path – オプション — ページの相対パスです。このページが親[parent]である場合、パンくずリストのリンクに使用されます。

上記の例では、配列を使用して拡張機能のパンくずリストを作成する方法を確認できます。WooCommerce は、タイトル配列の最初の部分にパス値につながるリンクを添付します。後続のすべての部分はテキストとしてレンダリングされ、リンクされません。

画面 ID [screen ID] の決定に関する注意

WooCommerce Admin は、さまざまなタブやサブセクションがある可能性のある管理ページをより正確に識別できるように、独自のバージョンの get_current_screen() を使用します。

この ID の形式は、ページに存在する構造要素によって異なる場合があります。関数が生成する形式には次のようなものがあります。

{$current_screen->action}-{$current_screen->action}-tab-section
{$current_screen->action}-{$current_screen->action}-tab
タブが存在しない場合は {$current_screen->action}-{$current_screen->action}
アクションまたはタブが存在しない場合は {$current_screen->action}

拡張機能でタブやサブセクションを含む新しいページを追加する場合は、必ず wc_admin_pages_with_tabs および wc_admin_page_tab_sections フィルターを使用して、WooCommerce でそれらの正確な画面 ID を生成してください。

また、wc_admin_current_screen_id フィルターを使用して、画面 ID 生成の動作に必要な変更を加えることもできます。

React を利用したページの登録

React を利用したページを登録するには、wc_admin_register_page() 関数を使用します。この関数は、さまざまな引数を受け入れます。

id – 必須 — コントローラーでページを識別します。
parent – オプション — ページが親の子であることを示し (親[parent]の ID を使用)、パンくずリストの生成に使用されます。
title – 必須 — ページのタイトルに対応し、パンくずリストの作成に使用されます。ここでは、文字列またはパンくずリストの配列を指定できます。
path – 必須 — ページのパス (#wc-admin を基準) です。このページを識別し、このページが親である場合にパンくずリストをリンクするために使用されます。
capacity – オプション — このページにアクセスするために必要なユーザー機能。デフォルト値は manage_options です。
icon – オプション — これを使用して、Dashicons ヘルパークラスまたは base64 でエンコードされた SVG を適用します。dashicon クラス名全体 (dashicons-*) を含めます。ただし、これは WooCommerce 管理ナビゲーションには含まれません。
position – オプション — 親ページのメニュー項目の位置。add_menu_page() を参照してください。
nav_args – オプション — これらは、WooCommerce ナビゲーションにアイテムを登録するための引数です。(使用方法は下記を参照)
nav_args[ ‘order’ ] – 表示用の注文番号。
nav_args[ ‘parent’ ] – アイテムが属するメニュー。例: woocommerce、woocommerce-settings、woocommerce-analytics。拡張機能によって追加されたカテゴリも利用できます。

React を利用したページの登録は PHP ページの接続と似ていますが、いくつか重要な違いがあります。ページを登録すると、親の値に基づいて適切な階層で、そのページの WordPress メニュー項目が自動的に作成されます。

例: 新しい WooCommerce 管理ページの追加

function add_extension_register_page() {
    if ( ! function_exists( 'wc_admin_register_page' ) ) {
        return;
    }

    wc_admin_register_page( array(
        'id'       => 'my-example-page',
        'title'    => 'My Example Page',
        'parent'   => 'woocommerce',
        'path'     => '/example',
        'nav_args' => array(
            'order'  => 10,
            'parent' => 'woocommerce',
        ),
    ) );
}
add_action( 'admin_menu', 'add_extension_register_page' );

上記の例では、admin_menu アクションにフックした関数に wc_admin_register_page() の呼び出しをカプセル化しました。コントローラでページを登録したら、クライアントサイドに React コンポーネントを提供できます。

import { addFilter } from '@wordpress/hooks';

const MyExamplePage = () => <h1>My Example Extension</h1>;

addFilter( 'woocommerce_admin_pages_list', 'my-namespace', ( pages ) => {
    pages.push( {
        container: MyExamplePage,
        path: '/example',
        breadcrumbs: [ 'My Example Page' ],
        navArgs: {
            id: 'my-example-page',
        },
    } );

    return pages;
} );

上記では、デモンストレーションのために単純な機能的な React コンポーネントを作成していますが、実際の拡張機能では、コンポーネントのネストがより複雑になる可能性があります。

WooCommerce 管理ページのリストにコンポーネントを提供する場合、navArgs.id に指定した値が、wc_admin_register_page() の呼び出しでページコントローラーに登録するページの id と一致することを確認することが重要です。

さらに読む

ページ登録の仕組みについて詳しくは、WooCommerce コアコードリファレンスの PageController クラスをご覧ください。WooCommerce Admin が既存のコアページを登録する方法と、WooCommerce が React を利用した Analytics レポートページを登録する方法を確認することで、2 つのページ登録方法の実際の例を確認できます。