インタラクティビティAPIリファレンス - APIリファレンス（API Reference）

ディレクティブとは何ですか？
ディレクティブのリスト
ディレクティブの値はストアプロパティへの参照です
ストア
サーバー機能

ディレクティブとは何ですか？

ディレクティブは、ブロックのマークアップに追加されるカスタム属性で、DOM要素に動作を追加します。これは、render.phpファイル（動的ブロック用）またはsave.jsファイル（静的ブロック用）で行うことができます。

インタラクティビティAPIのディレクティブは、data-プレフィックスを使用します。以下は、HTMLマークアップで使用されるディレクティブの例です。

<div
  data-wp-interactive="myPlugin"
  data-wp-context='{ "isOpen": false }'
  data-wp-watch="callbacks.logIsOpen"
>
  <button
   data-wp-on--click="actions.toggle"
   data-wp-bind--aria-expanded="context.isOpen"
   aria-controls="p-1"
  >
   Toggle
  </button>
  <p id="p-1" data-wp-bind--hidden="!context.isOpen">
   This element is now visible!
  </p>
</div>

ディレクティブは、HTMLタグプロセッサを使用して動的に注入することもできます。

ディレクティブを使用すると、副作用、状態、イベントハンドラ、属性、またはコンテンツなどのインタラクションを直接管理できます。

ディレクティブのリスト

wp-interactive


``````bash
<!-- Let's make this element and its children interactive and set the namespace -->
<div
  data-wp-interactive="myPlugin"
  data-wp-context='{ "myColor" : "red", "myBgColor": "yellow" }'
>
  <p>I'm interactive now, <span data-wp-style--background-color="context.myBgColor">and I can use directives!</span></p>
  <div>
   <p>I'm also interactive, <span data-wp-style--color="context.myColor">and I can also use directives!</span></p>
  </div>
</div>
<!-- This is also valid -->
<div
  data-wp-interactive='{ "namespace": "myPlugin" }'
  data-wp-context='{ "myColor" : "red", "myBgColor": "yellow" }'
>
  <p>I'm interactive now, <span data-wp-style--background-color="context.myBgColor">and I can use directives!</span></p>
  <div>
   <p>I'm also interactive, <span data-wp-style--color="context.myColor">and I can also use directives!</span></p>
  </div>
</div>
`

 <a name="wp-context"></a>
### wp-context
特定のHTMLノードとその子要素に利用可能な**ローカル**状態を提供します。  
`````wp-context`````ディレクティブは、値として文字列化されたJSONを受け入れます。  
``````bash
// render.php
<div data-wp-context='{ "post": { "id": <?php echo $post->ID; ?> } }' >
  <button data-wp-on--click="actions.logId" >
   Click Me!
  </button>
</div>
`

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
  actions: {
   logId: () => {
   const { post } = getContext();
   console.log( post.id );
   },
  },
} );

異なるコンテキストは異なるレベルで定義でき、深いレベルは親のコンテキストと自分のコンテキストをマージします：

<div data-wp-context='{ "foo": "bar" }'>
  <span data-wp-text="context.foo"><!-- Will output: "bar" --></span>
  <div data-wp-context='{ "bar": "baz" }'>
   <span data-wp-text="context.foo"><!-- Will output: "bar" --></span>
   <div data-wp-context='{ "foo": "bob" }'>
   <span data-wp-text="context.foo"><!-- Will output: "bob" --></span>
   </div>
  </div>
</div>

wp-bind

このディレクティブは、真偽値または文字列値に基づいて要素のHTML属性を設定することを許可します。構文はdata-wp-bind--attributeに従います。

<li data-wp-context='{ "isMenuOpen": false }'>
  <button
   data-wp-on--click="actions.toggleMenu"
   data-wp-bind--aria-expanded="context.isMenuOpen"
  >
   Toggle
  </button>
  <div data-wp-bind--hidden="!context.isMenuOpen">
   <span>Title</span>
   <ul>
   SUBMENU ITEMS
   </ul>
  </div>
</li>

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
  actions: {
   toggleMenu: () => {
   const context = getContext();
   context.isMenuOpen = !context.isMenuOpen;
   },
  },
} );


- 要素が作成されたとき 
- 最終的なディレクティブの値を取得するために関与する`````state`````または`````context`````のプロパティのいずれかに変更があるたびに（コールバック内または参照として渡された式内）
`````wp-bind`````ディレクティブが最終値を取得するためにコールバックを参照する場合：  
- `````wp-bind`````ディレクティブは、コールバック内で使用される`````state`````または`````context`````のプロパティのいずれかに変更があるたびに実行されます。 
- コールバック関数で返された値は、関連する属性の値を変更するために使用されます。
`````wp-bind`````は、DOM要素が適用されるときに、その値に応じて異なる動作をします：  
- 値が`````true`````の場合、属性が追加されます：`````<div attribute>

値がfalseの場合、属性が削除されます：<div>
値が文字列の場合、属性がその値で追加されます：<div attribute="value"
属性名がaria-またはdata-で始まり、値が真偽値（trueまたはfalse）の場合、属性はDOMに追加され、真偽値が文字列として割り当てられます：<div aria-attribute="true">

wp-class

このディレクティブは、真偽値に応じてHTML要素にクラスを追加または削除します。構文はdata-wp-class--classnameに従います。

<div>
  <li
   data-wp-context='{ "isSelected": false }'
   data-wp-on--click="actions.toggleSelection"
   data-wp-class--selected="context.isSelected"
  >
   Option 1
  </li>
  <li
   data-wp-context='{ "isSelected": false }'
   data-wp-on--click="actions.toggleSelection"
   data-wp-class--selected="context.isSelected"
  >
   Option 2
  </li>
</div>

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
  actions: {
   toggleSelection: () => {
   const context = getContext();
   context.isSelected = !context.isSelected
   }
  }
} );


- 要素が作成されたとき 
- 最終的なディレクティブの値を取得するために関与する`````state`````または`````context`````のプロパティのいずれかに変更があるたびに（コールバック内または参照として渡された式内）
ディレクティブによって受け取られた真偽値は、`````true`````のときに関連するクラス名をトグル（追加または削除）するために使用されます。  
`````wp-class`````ディレクティブを使用する際は、クラス名にはキャメルケースではなくケバブケースを使用することをお勧めします。これは、HTML属性が大文字と小文字を区別しないため、HTMLは`````data-wp-class--isDark`````を`````data-wp-class--isdark`````や`````DATA-WP-CLASS--ISDARK`````と同じように扱うからです。  
したがって、たとえば、クラス名`````is-dark`````を`````isDark`````の代わりに、`````data-wp-class--is-dark`````を`````data-wp-class--isDark`````の代わりに使用してください：  
``````bash
<!-- Recommended -->
<div data-wp-class--is-dark="context.isDarkMode">
  <!-- ... -->
</div>
<!-- Not recommended -->
<div data-wp-class--isDark="context.isDarkMode">
  <!-- ... -->
</div>
`

/* Recommended */
.is-dark {
  /* ... */
}
/* Not recommended */
.isDark {
  /* ... */
}

wp-style

このディレクティブは、値に応じてHTML要素にインラインスタイルを追加または削除します。構文はdata-wp-style--css-propertyに従います。

<div data-wp-context='{ "color": "red" }' >
  <button data-wp-on--click="actions.toggleContextColor">Toggle Color Text</button>
  <p data-wp-style--color="context.color">Hello World!</p>
</div>
>

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
  actions: {
   toggleContextColor: () => {
   const context = getContext();
   context.color = context.color === 'red' ? 'blue' : 'red';
   },
  },
} );


- 要素が作成されたとき 
- 最終的なディレクティブの値を取得するために関与する`````state`````または`````context`````のプロパティのいずれかに変更があるたびに（コールバック内または参照として渡された式内）
ディレクティブによって受け取られた値は、関連するCSSプロパティを持つスタイル属性を追加または削除するために使用されます：  
- 値が`````false`````の場合、スタイル属性が削除されます：`````<div>

値が文字列の場合、属性がその値で追加されます：<div style="css-property: value;">

wp-text

HTML要素の内部テキストを設定します。

<div data-wp-context='{ "text": "Text 1" }'>
  <span data-wp-text="context.text"></span>
  <button data-wp-on--click="actions.toggleContextText">
   Toggle Context Text
  </button>
</div>

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
  actions: {
   toggleContextText: () => {
   const context = getContext();
   context.text = context.text === 'Text 1' ? 'Text 2' : 'Text 1';
   },
  },
} );


- 要素が作成されたとき 
- 最終的なディレクティブの値を取得するために関与する`````state`````または`````context`````のプロパティのいずれかに変更があるたびに（コールバック内または参照として渡された式内）
返された値は、要素の内部コンテンツを変更するために使用されます：`````<div>value</div>`````。  
 <a name="wp-on"></a>
### wp-on
ディレクティブコードがイベントオブジェクトへの同期アクセスを必要としない場合は、よりパフォーマンスの良い[`````wp-on-async`````](#wp-on-async)を使用することを検討してください。同期アクセスが必要な場合は、同期APIを呼び出した後にメインスレッドに戻る[`````async action`````](#async-actions)を実装することを検討してください。   
このディレクティブは、`````click`````や`````keyup`````のようなディスパッチされたDOMイベントでコードを実行します。構文は`````data-wp-on--[event]`````（`````data-wp-on--click`````や`````data-wp-on--keyup`````のように）です。  
``````bash
<button data-wp-on--click="actions.logTime" >
  Click Me!
</button>
`

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
  actions: {
   logTime: ( event ) => {
   console.log( new Date() )
   },
  },
} );


参照として渡されたコールバックは[イベント](https://developer.mozilla.org/en-US/docs/Web/API/Event)（`````event`````）を受け取り、このコールバックによって返された値は無視されます。  
 <a name="wp-on-async"></a>
### wp-on-async
このディレクティブは、`````wp-on`````のよりパフォーマンスの良いアプローチです。長いタスクに寄与しないようにすぐにメインに戻り、メインスレッドで待機している他のインタラクションが早く実行できるようにします。`````event`````オブジェクトへの同期アクセスが必要ない場合は、この非同期バージョンを使用してください。特に、`````event.preventDefault()`````、`````event.stopPropagation()`````、`````event.stopImmediatePropagation()`````のメソッドに関してです。  
 <a name="wp-on-window"></a>
### wp-on-window
ディレクティブコードがイベントオブジェクトへの同期アクセスを必要としない場合は、よりパフォーマンスの良い[`````wp-on-async-window`````](#wp-on-async-window)を使用することを検討してください。同期アクセスが必要な場合は、同期APIを呼び出した後にメインスレッドに戻る[`````async action`````](#async-actions)を実装することを検討してください。   
このディレクティブを使用すると、`````resize`````、`````copy`````、`````focus`````のようなグローバルウィンドウイベントを添付し、それらが発生したときに定義されたコールバックを実行できます。  
[サポートされているウィンドウイベントのリスト。](https://developer.mozilla.org/en-US/docs/Web/API/Window#events)  
このディレクティブの構文は`````data-wp-on-window--[window-event]`````（`````data-wp-on-window--resize`````や`````data-wp-on-window--languagechange`````のように）です。  
``````bash
<div data-wp-on-window--resize="callbacks.logWidth"></div>
`

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
   callbacks: {
   logWidth() {
   console.log( 'Window width: ', window.innerWidth );
   },
   },
} );

参照として渡されたコールバックはイベント（event）を受け取り、このコールバックによって返された値は無視されます。要素がDOMから削除されると、イベントリスナーも削除されます。

wp-on-async-window

 <a name="wp-on-document"></a>
### wp-on-document
ディレクティブコードがイベントオブジェクトへの同期アクセスを必要としない場合は、よりパフォーマンスの良い[`````wp-on-async-document`````](#wp-on-async-document)を使用することを検討してください。同期アクセスが必要な場合は、同期APIを呼び出した後にメインスレッドに戻る[`````async action`````](#async-actions)を実装することを検討してください。   
このディレクティブを使用すると、`````scroll`````、`````mousemove`````、`````keydown`````のようなグローバルドキュメントイベントを添付し、それらが発生したときに定義されたコールバックを実行できます。  
[サポートされているドキュメントイベントのリスト。](https://developer.mozilla.org/en-US/docs/Web/API/Document#events)  
このディレクティブの構文は`````data-wp-on-document--[document-event]`````（`````data-wp-on-document--keydown`````や`````data-wp-on-document--selectionchange`````のように）です。  
``````bash
<div data-wp-on-document--keydown="callbacks.logKeydown"></div>
`

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
   callbacks: {
   logKeydown(event) {
   console.log( 'Key pressed: ', event.key );
   },
  },
} );

wp-on-async-document

 <a name="wp-watch"></a>
### wp-watch
ノードが作成されたときにコールバックを実行し、状態またはコンテキストが変更されたときに再度実行します。  
`````data-wp-watch--[unique-id]`````の構文を使用して、同じDOM要素に複数の副作用を添付できます。  
`````unique-id`````は、グローバルに一意である必要はありません。単に、そのDOM要素の`````wp-watch`````ディレクティブの他の一意のIDと異なる必要があります。  
``````bash
<div
  data-wp-context='{ "counter": 0 }'
  data-wp-watch="callbacks.logCounter"
>
  <p>Counter: <span data-wp-text="context.counter"></span></p>
  <button data-wp-on--click="actions.increaseCounter">+</button>
  <button data-wp-on--click="actions.decreaseCounter">-</button>
</div>
`

上記のディレクティブで使用されるストアを参照してください

store( "myPlugin", {
  actions: {
   increaseCounter: () => {
   const context = getContext();
   context.counter++;
   },
   decreaseCounter: () => {
   const context = getContext();
   context.counter--;
   },
  },
  callbacks: {
   logCounter: () => {
   const { counter } = getContext();
   console.log("Counter is " + counter + " at " + new Date() );
   },
  },
} );


- 要素が作成されたとき 
- コールバック内で使用される`````state`````または`````context`````のプロパティのいずれかが変更されるたびに
`````wp-watch`````ディレクティブは関数を返すことがあります。返された場合、その関数はクリーンアップロジックとして使用されます。つまり、コールバックが再度実行される直前に実行され、要素がDOMから削除されるときにも実行されます。  
このディレクティブのいくつかの使用例は次のとおりです：  
- ロギング 
- ページのタイトルを変更する 
- `````.focus()`````を持つ要素にフォーカスを設定する。 
- 特定の条件が満たされたときに状態またはコンテキストを変更する
 <a name="wp-init"></a>
### wp-init
このディレクティブは、ノードが作成されたときにのみコールバックを実行します。  
`````wp-init`````の構文を使用して、同じDOM要素に複数の`````data-wp-init--[unique-id]`````を添付できます。  
`````unique-id`````は、グローバルに一意である必要はありません。単に、そのDOM要素の`````wp-init`````ディレクティブの他の一意のIDと異なる必要があります。  
``````bash
<div data-wp-init="callbacks.logTimeInit">
  <p>Hi!</p>
</div>
`

同じDOM要素に複数のwp-initディレクティブがある別の例を示します。

<form
  data-wp-init--log="callbacks.logTimeInit"
  data-wp-init--focus="callbacks.focusFirstElement"
>
  <input type="text">
</form>

上記のディレクティブで使用されるストアを参照してください

import { store, getElement } from '@wordpress/interactivity';
store( "myPlugin", {
  callbacks: {
   logTimeInit: () => console.log( `Init at ` + new Date() ),
   focusFirstElement: () => {
   const { ref } = getElement();
   ref.querySelector( 'input:first-child' ).focus(),
   },
  },
} );

 <a name="wp-run"></a>
### wp-run
このディレクティブは、ノードのレンダリング実行中に渡されたコールバックを実行します。  
`````useState`````、`````useWatch`````、または`````useEffect`````のようなフックを渡されたコールバック内で使用および構成し、以前のディレクティブよりも柔軟性のある独自のロジックを作成できます。  
`````wp-run`````の構文を使用して、同じDOM要素に複数の`````data-wp-run--[unique-id]`````を添付できます。  
`````unique-id`````は、グローバルに一意である必要はありません。単に、そのDOM要素の`````wp-run`````ディレクティブの他の一意のIDと異なる必要があります。  
``````bash
<div data-wp-run="callbacks.logInView">
  <p>Hi!</p>
</div>
`

上記のディレクティブで使用されるストアを参照してください

import { getElement, store, useState, useEffect } from '@wordpress/interactivity';
// Unlike `data-wp-init` and `data-wp-watch`, you can use any hooks inside
// `data-wp-run` callbacks.
const useInView = () => {
  const [ inView, setInView ] = useState( false );
  useEffect( () => {
   const { ref } = getElement();
   const observer = new IntersectionObserver( ( [ entry ] ) => {
   setInView( entry.isIntersecting );
   } );
   observer.observe( ref );
   return () => ref && observer.unobserve( ref );
  }, []);
  return inView;
};
store( 'myPlugin', {
  callbacks: {
   logInView: () => {
   const isInView = useInView();
   useEffect( () => {
   if ( isInView ) {
   console.log( 'Inside' );
   } else {
   console.log( 'Outside' );
   }
   });
   }
  },
} );

(P)Reactコンポーネントと同様に、refは最初のレンダリング中にgetElement()からnullです。DOM要素の参照に適切にアクセスするには、通常、useEffect、useInit、またはuseWatchのようなエフェクトのようなフックを使用する必要があります。これにより、getElement()がコンポーネントがマウントされた後に実行され、refが利用可能になります。

wp-key


キーは、兄弟要素の中で要素を一意に識別する文字列である必要があります。通常、リスト項目のような繰り返し要素に使用されます。例えば：  
``````bash
<ul>
  <li data-wp-key="unique-id-1">Item 1</li>
  <li data-wp-key="unique-id-2">Item 2</li>
</ul>
`

しかし、他の要素にも使用できます：

<div>
  <a data-wp-key="previous-page" ...>Previous page</a>
  <a data-wp-key="next-page" ...>Next page</a>
</div>

リストが再レンダリングされると、インタラクティビティAPIはキーによって要素を一致させ、アイテムが追加/削除/再配置されたかどうかを判断します。キーのない要素は不必要に再作成される可能性があります。

wp-each


各アイテムは、デフォルトで`````item`````という名前でコンテキストに含まれ、テンプレート内のディレクティブは現在のアイテムにアクセスできます。  
例えば、次のHTMLを考えてみましょう。  
``````bash
<ul data-wp-context='{ "list": [ "hello", "hola", "olá" ] }'>
  <template data-wp-each="context.list" >
   <li data-wp-text="context.item"></li>
  </template>
</ul>
`

次の出力が生成されます：

<ul data-wp-context='{ "list": [ "hello", "hola", "olá" ] }'>
  <li data-wp-text="context.item">hello</li>
  <li data-wp-text="context.item">hola</li>
  <li data-wp-text="context.item">olá</li>
</ul>

コンテキスト内のアイテムを保持するプロパティは、ディレクティブ名にサフィックスを渡すことで変更できます。次の例では、デフォルトのプロパティがitemからgreetingに変更されます。

<ul data-wp-context='{ "list": [ "hello", "hola", "olá" ] }'>
  <template data-wp-each--greeting="context.list" >
   <li data-wp-text="context.greeting"></li>
  </template>
</ul>

デフォルトでは、レンダリングされたノードのキーとして各要素を使用しますが、必要に応じてキーを取得するためのパスを指定することもできます。たとえば、リストがオブジェクトを含む場合です。

そのためには、data-wp-each-keyを<template>タグで使用し、テンプレートコンテンツ内ではdata-wp-keyを使用しない必要があります。これは、data-wp-eachが各レンダリングされたアイテムの周りにコンテキストプロバイダーラッパーを作成し、それらのラッパーがkeyプロパティを必要とするからです。

<ul data-wp-context='{
  "list": [
   { "id": "en", "value": "hello" },
   { "id": "es", "value": "hola" },
   { "id": "pt", "value": "olá" }
  ]
}'>
  <template
   data-wp-each--greeting="context.list"
   data-wp-each-key="context.greeting.id"
  >
   <li data-wp-text="context.greeting.value"></li>
  </template>
</ul>

wp-each-child

サーバーサイドでレンダリングされたリストの場合、data-wp-each-childという別のディレクティブが、ハイドレーションが期待通りに機能することを保証します。このディレクティブは、サーバーでディレクティブが処理されるときに自動的に追加されます。

<ul data-wp-context='{ "list": [ "hello", "hola", "olá" ] }'>
  <template data-wp-each--greeting="context.list" >
   <li data-wp-text="context.greeting"></li>
  </template>
  <li data-wp-each-child>hello</li>
  <li data-wp-each-child>hola</li>
  <li data-wp-each-child>olá</li>
</ul>

ディレクティブの値はストアプロパティへの参照です

ディレクティブに割り当てられた値は、特定の状態、アクション、または副作用を指す文字列です。

次の例では、ゲッターを使用してstate.isPlaying派生値を定義します。

const { state } = store( "myPlugin", {
  state: {
   currentVideo: '',
   get isPlaying() {
   return state.currentVideo !== '';
   }
  },
} );

そして、文字列値"state.isPlaying"がこのセレクタの結果をdata-wp-bind--hiddenに割り当てるために使用されます。

<div data-wp-bind--hidden="!state.isPlaying" ... >
  <iframe ...></iframe>
</div>

これらのディレクティブに割り当てられた値は、ストア内の特定のプロパティへの参照です。これらは自動的にディレクティブに接続され、各ディレクティブは「どのストア要素を参照しているか」を知ることができます。追加の設定は必要ありません。

デフォルトでは、参照は現在の名前空間内のプロパティを指します。これは、data-wp-interactive属性を持つ最も近い祖先によって指定されたものです。異なる名前空間のプロパティにアクセスする必要がある場合は、アクセスされるプロパティが定義されている名前空間を明示的に設定できます。構文はnamespace::referenceで、namespaceを適切な値に置き換えます。

以下の例では、state.isPlayingがotherPluginから取得されていますが、myPluginからではありません：

<div data-wp-interactive="myPlugin">
  <div data-wp-bind--hidden="otherPlugin::!state.isPlaying" ... >
   <iframe ...></iframe>
   </div>
</div>

ストア

ストアは、ディレクティブにリンクされたロジック（アクション、副作用など）と、そのロジック内で使用されるデータ（状態、派生状態など）を作成するために使用されます。

ストアは通常、各ブロックのview.jsファイルで作成されますが、状態はブロックのrender.phpから初期化できます。

ストアの要素

状態

ページのHTMLノードに利用可能なデータを定義します。データを定義する2つの方法を区別することが重要です：

グローバル状態：store()関数を使用してstateプロパティで定義され、データはページのすべてのHTMLノードに利用可能です。
コンテキスト/ローカル状態：HTMLノード内でdata-wp-contextディレクティブを使用して定義され、データはそのHTMLノードとその子要素に利用可能です。アクション、派生状態、または副作用内でgetContext関数を使用してアクセスできます。

<div data-wp-context='{ "someText": "Hello World!" }'>
  <!-- Access global state -->
  <span data-wp-text="state.someText"></span>
  <!-- Access local state (context) -->
  <span data-wp-text="context.someText"></span>
</div>

const { state } = store( "myPlugin", {
  state: {
   someText: "Hello Universe!"
  },
  actions: {
   someAction: () => {
   state.someText // Access or modify global state - "Hello Universe!"
   const context = getContext();
   context.someText // Access or modify local state (context) - "Hello World!"
   },
  },
} )

アクション

アクションは通常のJavaScript関数です。通常、data-wp-onディレクティブ（イベントリスナーを使用）または他のアクションによってトリガーされます。

const { state, actions } = store("myPlugin", {
  actions: {
   selectItem: ( id ) => {
   const context = getContext();
   // `id` is optional here, so this action can be used in a directive.
   state.selected = id || context.id;
   },
   otherAction: () => {
   // but it can also be called from other actions.
   actions.selectItem(123); // it works and type is correct
   }
  }
});

非同期アクション

非同期アクションは、async/awaitの代わりにジェネレーターを使用する必要があります。

非同期関数では、制御は関数自体に渡されます。関数の呼び出し元は、関数が待機しているかどうか、そしてより重要なことに、awaitが解決され、関数が実行を再開したかどうかを知る方法がありません。この情報が必要です。スコープを復元するために。

2つのボタンを持つブロックを想像してください。一方はisOpen: trueを持つコンテキスト内にあり、もう一方はisOpen: falseを持っています：

<div data-wp-context='{ "isOpen": true }'>
  <button data-wp-on--click="actions.someAction">Click</button>
</div>
<div data-wp-context='{ "isOpen": false }'>
  <button data-wp-on--click="actions.someAction">Click</button>
</div>

アクションが非同期で長い遅延を待機する必要がある場合。

ユーザーが最初のボタンをクリックします。
スコープは最初のコンテキストを指します。isOpen: true。
最初のstate.isOpenへのアクセスは正しいです。getContextが現在のスコープを返すからです。
アクションは長い遅延を待機し始めます。
アクションが再開される前に、ユーザーが2番目のボタンをクリックします。
スコープは2番目のコンテキストに変更されます。isOpen: false。
最初のstate.isOpenへのアクセスは正しいです。getContextが現在のスコープを返すからです。
2番目のアクションが長い遅延を待機し始めます。
最初のアクションが待機を終了し、実行を再開します。
最初のアクションの2回目のstate.isOpenへのアクセスは不正確です。getContextが今や間違ったスコープを返すからです。

非同期アクションが待機を開始し、操作を再開するタイミングを知る必要があります。これがジェネレーターの役割です。

ストアは次のように書かれている場合、正常に機能します：

const { state } = store("myPlugin", {
  state: {
   get isOpen() {
   return getContext().isOpen;
   },
  },
  actions: {
   someAction: function* () {
   state.isOpen; // This context is correct because it's synchronous.
   yield longDelay(); // With generators, the caller controls when to resume this function.
   state.isOpen; // This context is correct because we restored the proper scope before we resumed the function.
   },
  },
});

上記のwp-on、wp-on-window、wp-on-documentで述べたように、非同期アクションは、アクションがasyncオブジェクトへの同期アクセスを必要とするため、前述のディレクティブのasyncバージョンを使用できない場合に使用する必要があります。アクションがevent.preventDefault()、event.stopPropagation()、またはevent.stopImmediatePropagation()を呼び出す必要がある場合は、同期アクセスが必要です。アクションコードが長いタスクに寄与しないようにするために、同期イベントAPIを呼び出した後に手動でメインスレッドに戻ることができます。例えば：

// Note: In WordPress 6.6 this splitTask function is exported by @wordpress/interactivity.
function splitTask() {
  return new Promise(resolve => {
   setTimeout(resolve, 0);
  });
}
store("myPlugin", {
  actions: {
   handleClick: function* (event) {
   event.preventDefault();
   yield splitTask();
   doTheWork();
   },
  },
});

多くの作業を行っている場合は、アクション内にこのようなyieldポイントを複数追加することをお勧めします。

副作用

状態の変更に自動的に反応します。通常、data-wp-watchまたはdata-wp-initディレクティブによってトリガーされます。

派生状態

状態の計算されたバージョンを返します。stateとcontextの両方にアクセスできます。

// view.js
const { state } = store( "myPlugin", {
  state: {
   amount: 34,
   defaultCurrency: 'EUR',
   currencyExchange: {
   USD: 1.1,
   GBP: 0.85,
   },
   get amountInUSD() {
   return state.currencyExchange[ 'USD' ] * state.amount;
   },
   get amountInGBP() {
   return state.currencyExchange[ 'GBP' ] * state.amount;
   },
  },
} );

コールバック内でのデータへのアクセス

store は、state、actions、またはcallbacksのようなすべてのストアプロパティを含みます。これらはstore()呼び出しによって返されるため、分割代入を使用してアクセスできます：

const { state, actions } = store( "myPlugin", {
  // ...
} );


``````bash
store( "myPlugin", {
  state: {
   someValue: 1,
  }
} );
const { state } = store( "myPlugin", {
  actions: {
   someAction() {
   state.someValue // = 1
   }
  }
} );
`

すべてのstore()呼び出しは同じ名前空間で同じ参照を返します。つまり、state、actionsなど、すべてのストア部分をマージした結果を含みます。

アクション、派生状態、または副作用内でコンテキストにアクセスするには、getContext関数を使用できます。
参照にアクセスするには、getElement関数を使用できます。

const { state } = store( "myPlugin", {
  state: {
   get someDerivedValue() {
   const context = getContext();
   const { ref } = getElement();
   // ...
   }
  },
  actions: {
   someAction() {
   const context = getContext();
   const { ref } = getElement();
   // ...
   }
  },
  callbacks: {
   someEffect() {
   const context = getContext();
   const { ref } = getElement();
   // ...
   }
  }
} );

このアプローチにより、ディレクティブを柔軟で強力にするいくつかの機能が可能になります：

アクションと副作用は、状態とコンテキストを読み取り、変更できます。
ブロック内のアクションと状態は、他のブロックからアクセスできます。
アクションと副作用は、通常のJavaScript関数ができることは何でもできます。たとえば、DOMにアクセスしたり、APIリクエストを行ったりできます。
副作用は状態の変更に自動的に反応します。

ストアの設定

クライアント側で

各ブロックのview.jsファイル内で 開発者は、アクション、副作用、または派生状態のような関数を参照して、状態とストアの要素の両方を定義できます。

ストアをJavaScriptで設定するために使用されるstoreメソッドは、@wordpress/interactivityからインポートできます。

// store
import { store, getContext } from '@wordpress/interactivity';
store( "myPlugin", {
  actions: {
   toggle: () => {
   const context = getContext();
   context.isOpen = !context.isOpen;
   },
  },
  callbacks: {
   logIsOpen: () => {
   const { isOpen } = getContext();
   // Log the value of `isOpen` each time it changes.
   console.log( `Is open: ${ isOpen }` );
   }
  },
});

サーバー側で

状態は、wp_interactivity_state()関数を使用してサーバーで初期化することもできます。通常、ブロックのrender.phpファイルでこれを行います（render.phpテンプレートはWordPress 6.1で導入されました）。


`````wp_interactivity_state`````関数は、参照として使用される名前空間を持つ`````string`````と、値を含む[連想配列](https://www.php.net/manual/en/language.types.array.php)の2つの引数を受け取ります。  
*`````state````` = `````{ someValue: 123 }`````でサーバーから初期化されたストアの例*  
``````bash
// render.php
wp_interactivity_state( 'myPlugin', array (
   'someValue' => get_some_value()
));
`

サーバーで状態を初期化すると、任意のWordPress APIを使用することもできます。たとえば、コア翻訳APIを使用して状態の一部を翻訳できます：

// render.php
wp_interactivity_state( 'favoriteMovies', array(
   "1" => array(
   "id" => "123-abc",
   "movieName" => __("someMovieName", "textdomain")
   ),
) );

プライベートストア

特定のストア名前空間をプライベートとしてマークすることができ、他の名前空間からその内容にアクセスできないようにします。そのメカニズムは、lockオプションをstore()呼び出しに追加することによって行われます。以下の例のように。このようにして、同じロックされた名前空間でのstore()のさらなる実行はエラーをスローし、その名前空間は最初のstore()呼び出しから返された場所でのみアクセスできることを意味します。これは、プラグインストアの一部を隠したい開発者に特に便利です。

const { state } = store(
   "myPlugin/private",
   { state: { messages: [ "private message" ] } },
   { lock: true }
);
// The following call throws an Error!
store( "myPlugin/private", { /* store part */ } );

プライベートストアを解除する方法もあります。ブール値を渡す代わりに、lock値として文字列を使用できます。そのような文字列は、同じ名前空間への後続のstore()呼び出しでその内容を解除するために使用できます。文字列ロックを知っているコードのみが、保護されたストア名を解除できます。これは、複数のJSモジュールで定義された複雑なストアに便利です。

const { state } = store(
   "myPlugin/private",
   { state: { messages: [ "private message" ] } },
   { lock: PRIVATE_LOCK }
);
// The following call works as expected.
store( "myPlugin/private", { /* store part */ }, { lock: PRIVATE_LOCK } );

ストアクライアントメソッド

ストア関数の他に、開発者がストア関数のデータにアクセスできるいくつかのメソッドもあります。

getContext()
getElement()

getContext()

ストアから関数を評価している要素によって継承されたコンテキストを取得します。返される値は、要素と関数がgetContext()を呼び出している名前空間によって異なります。特定のインタラクティブ領域のコンテキストを取得するために、オプションの名前空間引数を取ることもできます。

const context = getContext('namespace');

namespace（オプション）：インタラクティブ領域の名前空間に一致する文字列。提供されない場合は、現在のインタラクティブ領域のコンテキストを取得します。

// render.php
<div data-wp-interactive="myPlugin" data-wp-context='{ "isOpen": false }'>
   <button data-wp-on--click="actions.log">Log</button>
</div>

// store
import { store, getContext } from '@wordpress/interactivity';
store( "myPlugin", {
  actions: {
   log: () => {
   const context = getContext();
   // Logs "false"
   console.log('context => ', context.isOpen)
   // With namespace argument.
   const myPluginContext = getContext("myPlugin");
   // Logs "false"
   console.log('myPlugin isOpen => ', myPluginContext.isOpen);
   },
  },
});

getElement()

アクションがバインドされているか、呼び出されている要素の表現を取得します。そのような表現は読み取り専用で、DOM要素、プロパティ、およびローカル反応状態への参照を含みます。

それは2つのキーを持つオブジェクトを返します：

ref


##### attributes
`````attributes`````は、他のストア名前空間を参照できるゲッターを追加する[Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)を含みます。コード内のゲッターを確認してください。[リンク](https://github.com/WordPress/gutenberg/blob/8cb23964d58f3ce5cf6ae1b6f967a4b8d4939a8e/packages/interactivity/src/store.ts#L70)  
これらの属性は、その要素のディレクティブを含みます。ボタンの例では：  
``````bash
// store
import { store, getElement } from '@wordpress/interactivity';
store( "myPlugin", {
  actions: {
   log: () => {
   const element = getElement();
   // Logs attributes
   console.log('element attributes => ', element.attributes)
   },
  },
});
`

コードは次のようにログに記録します：

{
   "data-wp-on--click": 'actions.log',
   "children": ['Log'],
   "onclick": event => { evaluate(entry, event); }
}

withScope()

アクションは、呼び出されるときにスコープに依存する場合があります。たとえば、getContext()やgetElement()を呼び出すときです。

インタラクティビティAPIランタイムがコールバックを実行すると、スコープは自動的に設定されます。ただし、ランタイムによって実行されないコールバックからアクションを呼び出す場合、setInterval()コールバックのように、スコープが適切に設定されていることを確認する必要があります。この場合、withScope()関数を使用してスコープが適切に設定されていることを確認してください。


``````bash
store('mySliderPlugin', {
   callbacks: {
   initSlideShow: () => {
   setInterval(
   withScope( () => {
   actions.nextImage();
   } ),
   3_000
   );
   },
  },
})
`

サーバー機能

インタラクティビティAPIには、サーバー上で設定オプションを初期化および参照するための便利な関数が含まれています。これは、サーバー指令処理がブラウザに送信される前にHTMLマークアップを変更するために使用する初期データを供給するために必要です。また、非同期リクエスト（AJAX）や翻訳など、WordPressの多くのAPIを活用する素晴らしい方法でもあります。

wp_interactivity_config


 設定はクライアントでも利用可能ですが、静的情報です。  
 これは、ユーザーのインタラクションに基づいて更新されないサイトのインタラクションのためのグローバル設定と考えてください。  
 設定の例:  
``````bash
wp_interactivity_config( 'myPlugin', array( 'showLikeButton' => is_user_logged_in() ) );
`

取得の例:

wp_interactivity_config( 'myPlugin' );

この設定はクライアントで取得できます:

// view.js
const { showLikeButton } = getConfig();

wp_interactivity_state


 サーバー上でグローバル状態を初期化することにより、[AJAX](/read/wordpress/731afd95728012d5.md)や[ノンス](c96244420fe05525.md#nonce)など、多くの重要なWordPress APIを使用することができます。  
 `````wp_interactivity_state`````関数は、参照として使用されるネームスペースを含む文字列と、値を含む連想配列の2つの引数を受け取ります。  
 ここに、ノンスを持つWP Admin AJAXエンドポイントを渡す例があります。  
``````bash
// render.php
wp_interactivity_state(
   'myPlugin',
   array(
   'ajaxUrl' => admin_url( 'admin-ajax.php' ),
   'nonce'   => wp_create_nonce( 'myPlugin_nonce' ),
   ),
);
`

// view.js
const { state } = store( 'myPlugin', {
   actions: {
   *doSomething() {
   try {
   const formData = new FormData();
   formData.append( 'action', 'do_something' );
   formData.append( '_ajax_nonce', state.nonce );
   const data = yield fetch( state.ajaxUrl, {
   method: 'POST',
   body: formData,
   } ).then( ( response ) => response.json() );
   console.log( 'Server data!', data );
   } catch ( e ) {
   // Something went wrong!
   }
   },
   },
   }
);

wp_interactivity_process_directives


 これは、インタラクティビティAPIのサーバーサイドレンダリング部分のコア機能であり、公開されているため、ブロックであろうとなかろうと、任意のHTMLを処理できます。  
 このコード  
``````bash
wp_interactivity_state( 'myPlugin', array( 'greeting' => 'Hello, World!' ) );
$html_content = '<div data-wp-text="myPlugin::state.greeting"></div>';
$processed_html = wp_interactivity_process_directives( $html_content );
echo $processed_html;
`

は出力します:

<div data-wp-text="myPlugin::state.greeting">Hello, World!</div>

wp_interactivity_data_wp_context


 この関数は、サーバーサイドでレンダリングされたマークアップに`````data-wp-context`````属性を印刷するための推奨方法です。  
``````bash
$my_context = array(
   'counter' => 0,
   'isOpen'  => true,
);
?>
<div
 <?php echo wp_interactivity_data_wp_context( $my_context ); ?>
>
</div>
`

は出力します:

<div data-wp-context='{"counter":0,"isOpen":true}'>