TypeScriptの使用（Using TypeScript）

ローカルに @wordpress/interactivity をインストールする

まだ行っていない場合は、TypeScript が IDE でその型を使用できるように、@wordpress/interactivity パッケージをローカルにインストールする必要があります。次のコマンドを使用してこれを行うことができます：

npm install @wordpress/interactivity

そのパッケージを最新の状態に保つことも良い習慣です。

新しい型付きインタラクティブブロックのスキャフォールディング

ローカル環境で TypeScript を使用したインタラクティブブロックの例を探求したい場合は、@wordpress/create-block-interactive-template を使用できます。

まず、コンピュータに Node.js と npm がインストールされていることを確認してください。まだの場合は、Node.js 開発環境 ガイドを確認してください。

次に、@wordpress/create-block パッケージと @wordpress/create-block-interactive-template テンプレートを使用してブロックをスキャフォールディングします。

プラグインを作成したいフォルダーを選択し、そのフォルダー内のターミナルで次のコマンドを実行し、求められたときに typescript バリアントを選択します。

npx @wordpress/create-block@latest --template @wordpress/create-block-interactive-template

重要：ターミナルにスラッグを提供しないでください。そうしないと、create-block がどのバリアントを選択するかを尋ねず、デフォルトで非 TypeScript バリアントが選択されます。

最後に、はじめにガイド の指示に従い続けることができます。残りの指示は同じです。

ストアの型付け

ストアの構造と好みに応じて、ストアの型を生成するために選択できるオプションは3つあります：

• 1. クライアントストア定義から型を推論します。
• 2. サーバー状態を手動で型付けしますが、残りはクライアントストア定義から推論します。
• 3. すべての型を手動で記述します。
  

1. クライアントストア定義から型を推論する

store 関数を使用してストアを作成すると、TypeScript はストアのプロパティの型を自動的に推論します（state、actions、callbacks など）。これは、通常、単純な JavaScript オブジェクトを書くことで済み、TypeScript が正しい型を判断してくれることを意味します。

カウンターブロックの基本的な例から始めましょう。ブロックの view.ts ファイルにストアを定義し、初期のグローバル状態、アクション、およびコールバックを含めます。

// view.ts
const myStore = store( 'myCounterPlugin', {
   state: {
   counter: 0,
   },
   actions: {
   increment() {
   myStore.state.counter += 1;
   },
   },
   callbacks: {
   log() {
   console.log( `counter: ${ myStore.state.counter }` );
   },
   },
} );

myStore の型を TypeScript で検査すると、TypeScript が型を正しく推論できたことがわかります。

const myStore: {
   state: {
   counter: number;
   };
   actions: {
   increment(): void;
   };
   callbacks: {
   log(): void;
   };
};

state、actions、callbacks プロパティを分解しても、型は正しく機能します。

const { state } = store( 'myCounterPlugin', {
   state: {
   counter: 0,
   },
   actions: {
   increment() {
   state.counter += 1;
   },
   },
   callbacks: {
   log() {
   console.log( `counter: ${ state.counter }` );
   },
   },
} );

結論として、型を推論することは、store 関数への単一の呼び出しで定義されたシンプルなストアがあり、サーバーで初期化された状態を型付けする必要がない場合に便利です。

2. サーバー状態を手動で型付けし、残りをクライアントストア定義から推論する

wp_interactivity_state 関数でサーバーで初期化されたグローバル状態は、クライアントストア定義には存在せず、したがって手動で型付けする必要があります。しかし、ストアのすべての型を定義したくない場合は、クライアントストア定義の型を推論し、それをサーバーで初期化された状態の型とマージすることができます。

詳細については、サーバーサイドレンダリングガイド を訪れて、wp_interactivity_state とサーバーでのディレクティブの処理方法について学んでください。

前の例に従って、counter 状態の初期化をサーバーに移動しましょう。

wp_interactivity_state( 'myCounterPlugin', array(
   'counter' => 1,
));

次に、サーバー状態の型を定義し、それをクライアントストア定義から推論された型とマージします。

// Types the server state.
type ServerState = {
   state: {
   counter: number;
   };
};
// Defines the store in a variable to be able to extract its type later.
const storeDef = {
   actions: {
   increment() {
   state.counter += 1;
   },
   },
   callbacks: {
   log() {
   console.log( `counter: ${ state.counter }` );
   },
   },
};
// Merges the types of the server state and the client store definition.
type Store = ServerState & typeof storeDef;
// Injects the final types when calling the `store` function.
const { state } = store< Store >( 'myCounterPlugin', storeDef );

または、サーバーで定義された値とクライアントで定義された値の両方を含む全体の状態を型付けすることを気にしない場合は、state プロパティをキャストし、TypeScript にストアの残りを推論させることができます。

クライアントのグローバル状態に product という追加のプロパティがあると仮定しましょう。

type State = {
   counter: number; // The server state.
   product: number; // The client state.
};
const { state } = store( 'myCounterPlugin', {
   state: {
   product: 2,
   } as State, // Casts the entire state manually.
   actions: {
   increment() {
   state.counter * state.product;
   },
   },
} );

それでおしまいです。これで、TypeScript はストア定義から actions および callbacks プロパティの型を推論しますが、state プロパティには State 型を使用し、クライアントとサーバーの定義から正しい型を含むようにします。

結論として、このアプローチは、手動で型付けする必要があるサーバー状態がある場合に便利ですが、ストアの残りの型を推論したい場合にも便利です。

3. すべての型を手動で記述する

クライアントストア定義から TypeScript に推論させるのではなく、ストアのすべての型を手動で定義したい場合も可能です。store 関数にそれらを渡すだけです。

// Defines the store types.
interface Store {
   state: {
   counter: number; // Initial server state
   };
   actions: {
   increment(): void;
   };
   callbacks: {
   log(): void;
   };
}
// Pass the types when calling the `store` function.
const { state } = store< Store >( 'myCounterPlugin', {
   actions: {
   increment() {
   state.counter += 1;
   },
   },
   callbacks: {
   log() {
   console.log( `counter: ${ state.counter }` );
   },
   },
} );

それでおしまいです！結論として、このアプローチは、ストアのすべての型を制御したい場合に便利であり、手動で記述することを気にしない場合に便利です。

ローカルコンテキストの型付け

初期のローカルコンテキストは、data-wp-context ディレクティブを使用してサーバーで定義されます。

<div data-wp-context='{ "counter": 0 }'>...</div>

そのため、その型を手動で定義し、getContext 関数に渡して、返されるプロパティが正しく型付けされるようにする必要があります。

// Defines the types of your context.
type MyContext = {
   counter: number;
};
store( 'myCounterPlugin', {
   actions: {
   increment() {
   // Passes it to the getContext function.
   const context = getContext< MyContext >();
   // Now `context` is properly typed.
   context.counter += 1;
   },
   },
} );

コンテキストの型を何度も渡す必要がないように、型付き関数を定義し、その関数を getContext の代わりに使用することもできます。

// Defines the types of your context.
type MyContext = {
   counter: number;
};
// Defines a typed function. You only have to do this once.
const getMyContext = getContext< MyContext >;
store( 'myCounterPlugin', {
   actions: {
   increment() {
   // Use your typed function.
   const context = getMyContext();
   // Now `context` is properly typed.
   context.counter += 1;
   },
   },
} );

それでおしまいです！これで、正しい型でコンテキストプロパティにアクセスできます。

派生状態の型付け

派生状態は、グローバル状態またはローカルコンテキストに基づいて計算されるデータです。クライアントストア定義では、state オブジェクトのゲッターを使用して定義されます。

派生状態がインタラクティビティ API でどのように機能するかについて詳しく学ぶには、グローバル状態、ローカルコンテキスト、および派生状態の理解 ガイドを訪れてください。

前の例に従って、カウンターの2倍の派生状態を作成しましょう。

type MyContext = {
   counter: number;
};
const myStore = store( 'myCounterPlugin', {
   state: {
   get double() {
   const { counter } = getContext< MyContext >();
   return counter * 2;
   },
   },
   actions: {
   increment() {
   state.counter += 1; // This type is number.
   },
   },
} );

通常、派生状態がローカルコンテキストに依存している場合、TypeScript は正しい型を推論できます：

const myStore: {
   state: {
   readonly double: number;
   };
   actions: {
   increment(): void;
   };
};

しかし、派生状態の戻り値がグローバル状態の一部に直接依存している場合、TypeScript は循環参照があると主張するため、型を推論できません。

たとえば、この場合、state.double の型は state.counter に依存しており、state の型は state.double の型が定義されるまで完了しないため、循環参照が作成されます。

const { state } = store( 'myCounterPlugin', {
   state: {
   counter: 0,
   get double() {
   // TypeScript can't infer this return type because it depends on `state`.
   return state.counter * 2;
   },
   },
   actions: {
   increment() {
   state.counter += 1; // This type is now unknown.
   },
   },
} );

この場合、TypeScript の設定に応じて、TypeScript は循環参照について警告するか、単に any 型を state プロパティに追加します。

ただし、この問題を解決するのは簡単です。ゲッターの戻り値の型を手動で TypeScript に提供する必要があります。それを行うと、循環参照が消え、TypeScript は再びすべての state 型を推論できるようになります。

const { state } = store( 'myCounterPlugin', {
   state: {
   counter: 1,
   get double(): number {
   return state.counter * 2;
   },
   },
   actions: {
   increment() {
   state.counter += 1; // Correctly inferred!
   },
   },
} );

これが、前のストアの正しい推論された型です。

const myStore: {
   state: {
   counter: number;
   readonly double: number;
   };
   actions: {
   increment(): void;
   };
};

サーバーで wp_interactivity_state を使用する場合は、派生状態の初期値も次のように定義する必要があることを忘れないでください：

wp_interactivity_state( 'myCounterPlugin', array(
   'counter' => 1,
   'double'  => 2,
));

ただし、型を推論している場合は、派生状態の型を手動で定義する必要はありません。すでにクライアントのストア定義に存在します。

// You don't need to type `state.double` here.
type ServerState = {
   state: {
   counter: number;
   };
};
// The `state.double` type is inferred from here.
const storeDef = {
   state: {
   get double(): number {
   return state.counter * 2;
   },
   },
   actions: {
   increment() {
   state.counter += 1;
   },
   },
};
// Merges the types of the server state and the client store definition.
type Store = ServerState & typeof storeDef;
// Injects the final types when calling the `store` function.
const { state } = store< Store >( 'myCounterPlugin', storeDef );

それでおしまいです！これで、正しい型で派生状態プロパティにアクセスできます。

非同期アクションの型付け

インタラクティビティ API で TypeScript を使用する際に考慮すべきもう1つのことは、非同期アクションは非同期関数の代わりにジェネレーターで定義する必要があるということです。

インタラクティビティ API の非同期アクションでジェネレーターを使用する理由は、非同期アクションが yield の後に実行を続けるときに、最初にトリガーされたアクションからスコープを復元できるようにするためです。しかし、これは構文の変更だけであり、これらの関数は通常の非同期関数と同様に動作します。store 関数からの推論された型はこれを反映しています。

前の例に従って、ストアに非同期アクションを追加しましょう。

const { state } = store( 'myCounterPlugin', {
   state: {
   counter: 0,
   get double(): number {
   return state.counter * 2;
   },
   },
   actions: {
   increment() {
   state.counter += 1;
   },
   *delayedIncrement() {
   yield new Promise( ( r ) => setTimeout( r, 1000 ) );
   state.counter += 1;
   },
   },
} );

このストアの推論された型は：

const myStore: {
   state: {
   counter: number;
   readonly double: number;
   };
   actions: {
   increment(): void;
   // This behaves like a regular async function.
   delayedIncrement(): Promise< void >;
   };
};

これにより、外部関数で非同期アクションを使用でき、TypeScript は非同期関数の型を正しく使用します。

const someAsyncFunction = async () => {
   // This works fine and it's correctly typed.
   await actions.delayedIncrement( 2000 );
};

型を推論せず、ストア全体の型を手動で記述している場合は、非同期アクションのために非同期関数の型を使用できます。

type Store = {
   state: {
   counter: number;
   readonly double: number;
   };
   actions: {
   increment(): void;
   delayedIncrement(): Promise< void >; // You can use async functions here.
   };
};

非同期アクションを使用する際に考慮すべきことがあります。派生状態と同様に、非同期アクションが値を返す必要があり、この値がグローバル状態の一部に直接依存している場合、TypeScript は循環参照のために型を推論できません。

const { state, actions } = store( 'myCounterPlugin', {
   state: {
   counter: 0,
   },
   actions: {
   *delayedReturn() {
   yield new Promise( ( r ) => setTimeout( r, 1000 ) );
   return state.counter; // TypeScript can't infer this return type.
   },
   },
} );
In this case, just as we did with the derived state, we must manually type the return value of the generator.
const { state, actions } = store( 'myCounterPlugin', {
   state: {
   counter: 0,
   },
   actions: {
   *delayedReturn(): Generator< uknown, number, uknown > {
   yield new Promise( ( r ) => setTimeout( r, 1000 ) );
   return state.counter; // Now this is correctly inferred.
   },
   },
} );
That's it! Remember that the return type of a Generator is the second generic argument: `Generator< unknown, ReturnType, unknown >`.

複数の部分に分割されたストアの型付け

時には、ストアが異なるファイルに分割されることがあります。これは、異なるブロックが同じ名前空間を共有し、各ブロックが必要なストアの部分を読み込む場合に発生します。

2つのブロックの例を見てみましょう：

• todo-list：TODO リストを表示するブロック。
• add-post-to-todo：新しい TODO アイテムをリストに追加するボタンを表示するブロックで、テキストは「Read {$post_title}」です。

まず、todo-list ブロックのグローバルおよび派生状態をサーバーで初期化しましょう。

<?php
// todo-list-block/render.php
$todos = array( 'Buy milk', 'Walk the dog' );
wp_interactivity_state( 'myTodoPlugin', array(
  'todos'         => $todos,
  'filter'        => 'all',
  'filteredTodos' => $todos,
));
?>
<!-- HTML markup... -->

次に、サーバー状態を型付けし、クライアントストア定義を追加します。filteredTodos は派生状態なので、手動で型付けする必要はありません。

// todo-list-block/view.ts
type ServerState = {
   state: {
   todos: string[];
   filter: 'all' | 'completed';
   };
};
const todoList = {
   state: {
   get filteredTodos(): string[] {
   return state.filter === 'completed'
   ? state.todos.filter( ( todo ) => todo.includes( '' ) )
   : state.todos;
   },
   },
   actions: {
   addTodo( todo: string ) {
   state.todos.push( todo );
   },
   },
};
// Merges the inferred types with the server state types.
export type TodoList = ServerState & typeof todoList;
// Injects the final types when calling the `store` function.
const { state } = store< TodoList >( 'myTodoPlugin', todoList );

今のところ順調です。次に、add-post-to-todo ブロックを作成しましょう。

まず、サーバー状態に現在の投稿タイトルを追加します。

<?php
// add-post-to-todo-block/render.php
wp_interactivity_state( 'myTodoPlugin', array(
  'postTitle' => get_the_title(),
));
?>
<!-- HTML markup... -->

次に、そのサーバー状態を型付けし、クライアントストア定義を追加します。

// add-post-to-todo-block/view.ts
type ServerState = {
   state: {
   postTitle: string;
   };
};
const addPostToTodo = {
   actions: {
   addPostToTodo() {
   const todo = `Read: ${ state.postTitle }`.trim();
   if ( ! state.todos.includes( todo ) ) {
   actions.addTodo( todo );
   }
   },
   },
};
// Merges the inferred types with the server state types.
type Store = ServerState & typeof addPostToTodo;
// Injects the final types when calling the `store` function.
const { state, actions } = store< Store >( 'myTodoPlugin', addPostToTodo );

これはブラウザで正常に動作しますが、TypeScript はこのブロックで state と actions が state.todos と actions.addtodo を含まないと不満を言います。

これを修正するには、TodoList 型を todo-list ブロックからインポートし、他の型とマージする必要があります。

import type { TodoList } from '../todo-list-block/view';
// ...
// Merges the inferred types inferred the server state types.
type Store = TodoList & ServerState & typeof addPostToTodo;

それでおしまいです！これで、TypeScript は state.todos と actions.addTodo が add-post-to-todo ブロックで利用可能であることを認識します。

このアプローチにより、add-post-to-todo ブロックは既存の TODO リストと対話しながら、型安全性を維持し、共有ストアに独自の機能を追加できます。

add-post-to-todo 型を todo-list ブロックで使用する必要がある場合は、その型をエクスポートし、他の view.ts ファイルでインポートするだけです。

最後に、型を推論するのではなく、すべての型を手動で定義したい場合は、別のファイルにそれらを定義し、その定義をストアの各部分にインポートできます。TODO リストの例でそれを行う方法は次のとおりです：

// types.ts
interface Store {
   state: {
   todos: string[];
   filter: 'all' | 'completed';
   filtered: string[];
   postTitle: string;
   };
   actions: {
   addTodo( todo: string ): void;
   addPostToTodo(): void;
   };
}
export default Store;

// todo-list-block/view.ts
import type Store from '../types';
const { state } = store< Store >( 'myTodoPlugin', {
   // Everything is correctly typed here
} );

// add-post-to-todo-block/view.ts
import type Store from '../types';
const { state, actions } = store< Store >( 'myTodoPlugin', {
   // Everything is correctly typed here
} );

このアプローチにより、型を完全に制御でき、ストアのすべての部分で一貫性を確保できます。これは、複雑なストア構造がある場合や、複数のブロックやコンポーネントにわたって特定のインターフェースを強制したい場合に特に便利です。

型付きストアのインポートとエクスポート

インタラクティビティ API では、他の名前空間のストアに store 関数を使用してアクセスできます。

todo-list ブロックの例に戻りましょうが、今回は add-post-to-todo ブロックが別のプラグインに属し、したがって異なる名前空間を使用すると想像してみましょう。

// Import the store of the `todo-list` block.
const myTodoPlugin = store( 'myTodoPlugin' );
store( 'myAddPostToTodoPlugin', {
   actions: {
   addPostToTodo() {
   const todo = `Read: ${ state.postTitle }`.trim();
   if ( ! myTodoPlugin.state.todos.includes( todo ) ) {
   myTodoPlugin.actions.addTodo( todo );
   }
   },
   },
} );

これはブラウザで正常に動作しますが、TypeScript は myTodoPlugin.state と myTodoPlugin.actions が型付けされていないと不満を言います。

これを修正するには、myTodoPlugin プラグインが正しい型で store 関数を呼び出した結果をエクスポートし、それをスクリプトモジュールを使用して利用可能にすることができます。

// Export the already typed state and actions.
export const { state, actions } = store< TodoList >( 'myTodoPlugin', {
   // ...
} );

これで、add-post-to-todo ブロックは myTodoPlugin スクリプトモジュールから型付きストアをインポートでき、ストアが読み込まれるだけでなく、正しい型も含まれていることが保証されます。

import { store } from '@wordpress/interactivity';
import {
   state as todoState,
   actions as todoActions,
} from 'my-todo-plugin-module';
store( 'myAddPostToTodoPlugin', {
   actions: {
   addPostToTodo() {
   const todo = `Read: ${ state.postTitle }`.trim();
   if ( ! todoState.todos.includes( todo ) ) {
   todoActions.addTodo( todo );
   }
   },
   },
} );

my-todo-plugin-module スクリプトモジュールを依存関係として宣言する必要があることを忘れないでください。

他のストアがオプションであり、早期に読み込みたくない場合は、静的インポートの代わりに動的インポートを使用できます。

import { store } from '@wordpress/interactivity';
store( 'myAddPostToTodoPlugin', {
   actions: {
   *addPostToTodo() {
   const todoPlugin = yield import( 'my-todo-plugin-module' );
   const todo = `Read: ${ state.postTitle }`.trim();
   if ( ! todoPlugin.state.todos.includes( todo ) ) {
   todoPlugin.actions.addTodo( todo );
   }
   },
   },
} );

結論

このガイドでは、型を自動的に推論することから手動で定義することまで、インタラクティビティ API ストアの型付けに関するさまざまなアプローチを探求しました。また、サーバー初期化状態、ローカルコンテキスト、派生状態の処理方法や、非同期アクションの型付けについても説明しました。

型を推論するか手動で定義するかの選択は、特定のニーズとストアの複雑さに依存することを忘れないでください。どのアプローチを選んでも、TypeScript はより良く、より信頼性の高いインタラクティブブロックを構築するのに役立ちます。