@wordpress/preferences

インストール

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

npm install @wordpress/preferences --save

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

主要な概念

スコープ

多くのAPI呼び出しには、名前空間のように機能する「スコープ」パラメータが必要です。同じキーを持つ複数のパラメータがアプリケーションの異なる部分に適用される場合、スコープを使用することが最も効果的です。

キー

各設定は、文字列であるべきキーに対して設定されます。

値

値は任意の型であることができますが、サポートされる型は永続層の設定によって制限される場合があります。たとえば、設定がJSON形式でブラウザのlocalStorageに保存される場合、JSONシリアライズ可能な型のみを使用する必要があります。

デフォルト

デフォルトは、設定がundefinedであるときに返される値です。これらは永続化されず、メモリ内にのみ保持されます。アプリケーションの初期化中に保持されるべきです。

例

データストア

初期化時にアクションをディスパッチすることで、機能のデフォルト設定を設定します:

import { dispatch } from '@wordpress/data';
import { store as preferencesStore } from '@wordpress/preferences';
function initialize() {
   // ...
   dispatch( preferencesStore ).setDefaults(
   'namespace/editor-or-plugin-name',
   {
   myBooleanFeature: true,
   }
   );
   // ...
}

``````bash
wp.data
   .select( 'core/preferences' )
   .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 1
wp.data
   .dispatch( 'core/preferences' )
   .set( 'namespace/editor-or-plugin-name', 'myPreferenceName', 2 );
wp.data
   .select( 'core/preferences' )
   .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 2
`

``````bash
wp.data
   .select( 'core/preferences' )
   .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // true
wp.data
   .dispatch( 'core/preferences' )
   .toggle( 'namespace/editor-or-plugin-name', 'myPreferenceName' );
wp.data
   .select( 'core/preferences' )
   .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // false
`

永続層の設定

デフォルトでは、このパッケージは値をメモリ内にのみ保存します。しかし、オプションの永続層を介してブラウザストレージやデータベースに設定を永続化するように構成できます。

``````bash
wp.data.dispatch( 'core/preferences' ).setPersistenceLayer( {
   // `get` is asynchronous to support persisting preferences using a REST API.
   // it will immediately be called by `setPersistenceLayer` and the returned
   // value used as the initial state of the preferences.
   async get() {
   return JSON.parse( window.localStorage.getItem( 'MY_PREFERENCES' ) );
   },
   // `set` is synchronous. It's ok to use asynchronous code, but the
   // preferences store won't wait for a promise to resolve, the function is
   // 'fire and forget'.
   set( preferences ) {
   window.localStorage.setItem(
   'MY_PREFERENCES',
   JSON.stringify( preferences )
   );
   },
} );
`

データを非同期APIに永続化するアプリケーションでは、設定の読み込みがアプリケーションの起動を遅くする可能性があります。

推奨事項は、永続層のデータを事前に読み込み、特にデータを永続化するために非同期APIを使用している場合はローカルキャッシュに保持することです。

注意: 現在、getはsetPersistenceLayerがトリガーされたときにのみ呼び出されます。これは将来的に変更される可能性があるため、以下の例に示すようにローカルキャッシュを使用してgetを最適化することが賢明です。

// Preloaded data from the server.
let cache = preloadedData;
wp.data.dispatch( 'core/preferences' ).setPersistenceLayer( {
   async get() {
   if ( cache ) {
   return cache;
   }
   // Call to a made-up async API.
   return await api.preferences.get();
   },
   set( preferences ) {
   cache = preferences;
   api.preferences.set( { data: preferences } );
   },
} );

コンポーネント

``````bash
function MyEditorMenu() {
   return (
   <DropdownMenu>
   { () => (
   <MenuGroup label={ __( 'Features' ) }>
   <PreferenceToggleMenuItem
   scope="namespace/editor-or-plugin-name"
   name="myPreferenceName"
   label={ __( 'My feature' ) }
   info={ __( 'A really awesome feature' ) }
   messageActivated={ __( 'My feature activated' ) }
   messageDeactivated={ __( 'My feature deactivated' ) }
   />
   </MenuGroup>
   ) }
   </DropdownMenu>
   );
}
`

APIリファレンス

アクション

wp.data.dispatch( 'core/preferences' )から返されるオブジェクトには、次のアクション作成者のセットが利用可能です:

set

設定を値に設定する必要があることを示すアクションオブジェクトを返します

パラメータ

• scope string: 設定スコープ（例: core/edit-post）。
• name string: 設定名。
• value *: 設定する値。

返されるもの

• Object: アクションオブジェクト。

setDefaults

設定のデフォルトを設定する必要があることを示すアクションオブジェクトを返します。

パラメータ

• scope string: 設定スコープ（例: core/edit-post）。
• defaults Object<string, *>: 設定名と値のキー/バリューマップ。

返されるもの

• Object: アクションオブジェクト。

setPersistenceLayer

永続層を設定します。

永続層が設定されると、設定ストアは:

• getを即座に呼び出し、返された値にストアの状態を更新します。
• 設定が値を変更するたびに、すべての設定でsetを呼び出します。

setPersistenceLayerは、アプリケーションのライフサイクルの開始時に、他のアクションが設定ストアにディスパッチされる前にディスパッチされるべきです。

パラメータ

• persistenceLayer WPPreferencesPersistenceLayer: 永続層。

返されるもの

• Object: アクションオブジェクト。

toggle

設定を切り替える必要があることを示すアクションオブジェクトを返します。

パラメータ

• scope string: 設定スコープ（例: core/edit-post）。

• name string: 設定名。

セレクタ

wp.data.select( 'core/preferences' )から返されるオブジェクトには、次のセレクタが利用可能です:

get

特定のスコープに対して設定がアクティブかどうかを示すブール値を返します。

パラメータ

• state Object: ストアの状態。
• scope string: 機能のスコープ（例: core/edit-post）。
• name string: 機能の名前。

返されるもの

• *: 機能は有効ですか？

このパッケージへの貢献

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

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