コマンドの種類

コマンドを登録する方法は2つあります：静的または動的です。どちらの方法も、次の情報を提供するコマンドオブジェクトを引数として受け取ります：

  • name: コマンドの一意の機械可読名
  • label: 人間可読のラベル
  • icon: SVGアイコン
  • callback: コマンドが選択されたときに呼び出されるコールバック関数
  • context: （オプション）コマンドのコンテキスト

静的コマンド

静的コマンドは、wp.data.dispatch( wp.commands.store ).registerCommandアクションまたはwp.commands.useCommand Reactフックを使用して登録できます。静的コマンドは特定のアクションを実行するために一般的に使用されます。これには、新しいページを追加したり、エディターインターフェースのセクションを開いたりすることが含まれます。たとえば、エディタープリファレンスモーダルを開くことができます。以下のuseCommand コード例を参照してください。

動的コマンド

一方、動的コマンドは「コマンドローダー」、wp.commands.useCommandLoaderを使用して登録されます。これらのローダーは、コマンドパレットの入力にユーザーが入力した検索用語に依存するコマンドリストが必要な場合や、特定の条件が満たされたときにのみ利用可能なコマンドがある場合に必要です。

たとえば、ユーザーが「contact」と入力すると、コマンドパレットはその入力を使用して利用可能なページをフィルタリングし、連絡先ページを見つけようとします。以下のuseCommandLoader コード例を参照してください。

コンテキストコマンド

静的および動的コマンドはコンテキストに依存する場合があります。これは、特定のコンテキスト（たとえば、サイトエディターをナビゲートしているときやテンプレートを編集しているとき）で、特定のコマンドが優先され、コマンドパレットを開くとすぐに表示されることを意味します。また、コマンドパレットを入力しているとき、これらのコンテキストコマンドは他のコマンドの上に表示されます。

現在、2つのコンテキストが実装されています：

  • site-editor: サイトエディター（サイドバーが表示されている）でナビゲートしているときに設定されるコンテキストです。
  • site-editor-edit: サイトエディターでドキュメント（テンプレート、テンプレートパート、またはページ）を編集しているときに設定されるコンテキストです。
    コマンドパレットの使用が拡大するにつれて、さらに多くのコンテキストが追加されます。

特定のコンテキストにコマンドまたはコマンドローダーを添付するのは、contextプロパティ（上記の利用可能なコンテキストからの正しいコンテキスト値を使用）をuseCommandまたはuseCommandLoader呼び出しに追加するだけで簡単です。

WordPressデータAPI

コマンドパレットは、状態を操作するためのいくつかのセレクターとアクションを提供します。これには次のものが含まれます：

  • 次のセレクターgetCommandsおよびgetCommandLoaderを使用して登録されたコマンドとコマンドローダーを取得する
  • isOpenセレクターを使用してコマンドパレットが開いているかどうかを確認する。
  • openおよびcloseアクションを使用してプログラム的にコマンドパレットを開いたり閉じたりする。

詳細については、コマンドデータのドキュメントを参照してください。

インストール

モジュールをインストールします 

  1. npm install @wordpress/commands --save

このパッケージは、あなたのコードがES2015+環境で実行されることを前提としています。このような言語機能やAPIのサポートが限られているか、まったくない環境を使用している場合は、コードに@wordpress/babel-preset-defaultで提供されるポリフィルを含める必要があります。

API

ストア

コマンドネームスペースのストア定義。

関連

使用法 

  1. import { store as commandsStore } from '@wordpress/commands';
  2. import { useDispatch } from '@wordpress/data';
  3. ...
  4. const { open: openCommandCenter } = useDispatch( commandsStore );

タイプ

  • Object

useCommand

コマンドパレットにコマンドを添付します。静的コマンドに使用されます。

使用法 

  1. import { useCommand } from '@wordpress/commands';
  2. import { plus } from '@wordpress/icons';
  4. useCommand( {
  5.    name: 'myplugin/my-command-name',
  6.    label: __( 'Add new post' ),
  7.    icon: plus,
  8.    callback: ( { close } ) => {
  9.    document.location.href = 'post-new.php';
  10.    close();
  11.    },
  12. } );

パラメータ

  • コマンドimport('../store/actions').WPCommandConfig: コマンド設定。

useCommandLoader

コマンドパレットにコマンドローダーを添付します。動的コマンドに使用されます。

使用法 

  1. import { useCommandLoader } from '@wordpress/commands';
  2. import { post, page, layout, symbolFilled } from '@wordpress/icons';
  4. const icons = {
  5.    post,
  6.    page,
  7.    wp_template: layout,
  8.    wp_template_part: symbolFilled,
  9. };
  11. function usePageSearchCommandLoader( { search } ) {
  12.    // Retrieve the pages for the "search" term.
  13.    const { records, isLoading } = useSelect( ( select ) => {
  14.    const { getEntityRecords } = select( coreStore );
  15.    const query = {
  16.    search: !! search ? search : undefined,
  17.    per_page: 10,
  18.    orderby: search ? 'relevance' : 'date',
  19.    };
  20.    return {
  21.    records: getEntityRecords( 'postType', 'page', query ),
  22.    isLoading: ! select( coreStore ).hasFinishedResolution(
  23.    'getEntityRecords',
  24.    'postType', 'page', query ]
  25.    ),
  26.    };
  27.    }, [ search ] );
  29.    // Create the commands.
  30.    const commands = useMemo( () => {
  31.    return ( records ?? [] ).slice( 0, 10 ).map( ( record ) => {
  32.    return {
  33.    name: record.title?.rendered + ' ' + record.id,
  34.    label: record.title?.rendered
  35.    ? record.title?.rendered
  36.    : __( '(no title)' ),
  37.    icon: icons[ postType ],
  38.    callback: ( { close } ) => {
  39.    const args = {
  40.    postType,
  41.    postId: record.id,
  42.    ...extraArgs,
  43.    };
  44.    document.location = addQueryArgs( 'site-editor.php', args );
  45.    close();
  46.    },
  47.    };
  48.    } );
  49.    }, [ records, history ] );
  51.    return {
  52.    commands,
  53.    isLoading,
  54.    };
  55. }
  57. useCommandLoader( {
  58.    name: 'myplugin/page-search',
  59.    hook: usePageSearchCommandLoader,
  60. } );

パラメータ

  • ローダーimport('../store/actions').WPCommandLoaderConfig: コマンドローダー設定。

このパッケージへの貢献

これはGutenbergプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージはnpmに公開され、WordPressや他のソフトウェアプロジェクトで使用されています。

このパッケージやGutenberg全体への貢献について詳しく知りたい場合は、プロジェクトの主要な貢献者ガイドをお読みください。