APIスライス：React Hooks

Hooksの概要

RTK Queryの中核となる`createApi`メソッドは、ReduxコアライブラリやRedux Toolkitと同様に、UI非依存です。これらはすべてプレーンなJSロジックであり、どこでも使用できます。

しかし、RTK Queryは、各エンドポイントのReactフックを自動生成する機能も提供しています。これはReact自体に依存するため、RTK Queryは、この機能を含む`createApi`のカスタマイズ版を公開する代替エントリポイントを提供します。

import { createApi } from '@reduxjs/toolkit/query/react'

React固有の`createApi`を使用した場合、生成された`Api`スライス構造には、Reactフックのセットも含まれます。主要なエンドポイントフックは、エンドポイントの定義方法に合わせて`api.endpoints[endpointName].useQuery`または`api.endpoints[endpointName].useMutation`として利用できます。

同じフックは`Api`オブジェクトにも追加され、エンドポイント名とクエリ/ミューテーションの種類に基づいて自動生成された名前が付けられます。

例えば、`getPosts`と`updatePost`のエンドポイントがあると、これらのオプションが利用可能です。

生成されたReactフックの名前

// Hooks attached to the endpoint definition
const { data } = api.endpoints.getPosts.useQuery()
const [updatePost, { data }] = api.endpoints.updatePost.useMutation()

// Same hooks, but given unique names and attached to the API slice object
const { data } = api.useGetPostsQuery()
const [updatePost, { data }] = api.useUpdatePostMutation()

一般的な形式は`use(Endpointname)(Query|Mutation)`です。`use`が接頭辞として付き、エンドポイント名の最初の文字が大文字になり、種類に応じて`Query`または`Mutation`が追加されます。

RTK Queryは、より高度なユースケースのために追加のフックを提供しますが、すべてが`Api`オブジェクトに直接生成されるわけではありません。React固有の`createApi`で生成されるフックの完全なリストは以下のとおりです。

• useQuery（エンドポイント固有、`Api`オブジェクトにも生成されます）
• useMutation（エンドポイント固有、`Api`オブジェクトにも生成されます）
• useQueryState（エンドポイント固有）
• useQuerySubscription（エンドポイント固有）
• useLazyQuery（エンドポイント固有、`Api`オブジェクトにも生成されます）
• useLazyQuerySubscription（エンドポイント固有）
• usePrefetch（エンドポイント非依存）

上記の例では、apiの生成されたフックの完全なセットは次のようになります。

生成されたReact Hooks

/* Hooks attached to the `getPosts` query endpoint definition */
api.endpoints.getPosts.useQuery(arg, options)
api.endpoints.getPosts.useQueryState(arg, options)
api.endpoints.getPosts.useQuerySubscription(arg, options)
api.endpoints.getPosts.useLazyQuery(options)
api.endpoints.getPosts.useLazyQuerySubscription(options)

/* Hooks attached to the `updatePost` mutation endpoint definition */
api.endpoints.updatePost.useMutation(options)

/* Hooks attached to the `Api` object */
api.useGetPostsQuery(arg, options) // same as api.endpoints.getPosts.useQuery
api.useLazyGetPostsQuery(options) // same as api.endpoints.getPosts.useLazyQuery
api.useUpdatePostMutation(options) // same as api.endpoints.updatePost.useMutation
api.usePrefetch(endpointName, options)

機能比較

提供されているフックは、特定の状況に最適化されたオプションを提供するために、ある程度の機能重複があります。以下の表は、各フックのコア機能の比較を示しています。

機能	useQuery	useMutation	useQueryState	useQuerySubscription	useLazyQuery	useLazyQuerySubscription	usePrefetch
クエリ要求を自動的にトリガー	✔️			✔️
クエリ要求を手動でトリガー可能	✔️			✔️	✔️	✔️	✔️
ミューテーション要求を手動でトリガー可能		✔️
キャッシュされたデータをストアに保持するためにコンポーネントをサブスクライブ	✔️	✔️		✔️	✔️	✔️
ストアから要求ステータスとキャッシュされたデータを取得	✔️	✔️	✔️		✔️
要求ステータスとデータが利用可能になると再レンダリング	✔️	✔️	✔️		✔️
自動再フェッチをトリガーするためのポーリング/再フェッチオプションを受け入れる	✔️			✔️	✔️	✔️

useQuery

useQueryフックへのアクセス

const useQueryResult = api.endpoints.getPosts.useQuery(arg, options)
// or
const useQueryResult = api.useGetPostsQuery(arg, options)

シグネチャ

type UseQuery = (
  arg: any | SkipToken,
  options?: UseQueryOptions,
) => UseQueryResult

type UseQueryOptions = {
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
  skip?: boolean
  refetchOnMountOrArgChange?: boolean | number
  selectFromResult?: (result: UseQueryStateDefaultResult) => any
}

type UseQueryResult<T> = {
  // Base query state
  originalArgs?: unknown // Arguments passed to the query
  data?: T // The latest returned result regardless of hook arg, if present
  currentData?: T // The latest returned result for the current hook arg, if present
  error?: unknown // Error result if present
  requestId?: string // A string generated by RTK Query
  endpointName?: string // The name of the given endpoint for the query
  startedTimeStamp?: number // Timestamp for when the query was initiated
  fulfilledTimeStamp?: number // Timestamp for when the query was completed

  // Derived request status booleans
  isUninitialized: boolean // Query has not started yet.
  isLoading: boolean // Query is currently loading for the first time. No data yet.
  isFetching: boolean // Query is currently fetching, but might have data from an earlier request.
  isSuccess: boolean // Query has data from a successful load.
  isError: boolean // Query is currently in an "error" state.

  refetch: () => QueryActionCreatorResult // A function to force refetch the query - returns a Promise with additional methods
}

• パラメータ
  • arg：クエリ自体を構築するため、およびクエリのキャッシュキーとして使用されるクエリ引数。クエリをスキップする代替方法として`skipToken`もここで渡すことができます。skipTokenを参照
  • options：フックのフェッチ動作を制御するオプションのセット
• 戻り値
  • 現在の読み込み状態、API呼び出しから返された実際のデータまたはエラー、要求に関するメタデータ、データの`refetch`関数を格納するクエリ結果オブジェクト。`selectFromResult`でカスタマイズできます。

説明

エンドポイントからデータのフェッチを自動的にトリガーし、コンポーネントをキャッシュされたデータに「サブスクライブ」し、Reduxストアから要求ステータスとキャッシュされたデータを読み取るReactフック。読み込みステータスが変更され、データが利用可能になると、コンポーネントは再レンダリングされます。

クエリ引数はキャッシュキーとして使用されます。クエリ引数を変更すると、フックはキャッシュに存在しない場合にデータを再フェッチし、利用可能になるとそのクエリ引数のデータが返されます。

このフックはuseQueryStateとuseQuerySubscriptionの両方の機能を組み合わせたもので、ほとんどの状況で使用することを意図しています。

機能

• フック引数とキャッシュされたデータの存在に基づいて、データを取得するための要求を自動的にトリガーします。
• コンポーネントをサブスクライブしてキャッシュされたデータをストアに保持し、コンポーネントがアンマウントされるとサブスクライブを解除します。
• 対応する基準が満たされたときに自動再フェッチをトリガーするためのポーリング/再フェッチオプションを受け入れます。
• Reduxストアから最新の要求ステータスとキャッシュされたデータを取得します。
• 要求ステータスが変更され、データが利用可能になると再レンダリングされます。

skipToken

クエリオプションで`skip: true`を設定した場合と同じ効果を得るために、クエリ引数の代わりに`useQuery`、`useQueryState`、または`useQuerySubscription`に渡すことができます。

`arg`が`undefined`の場合にクエリをスキップする必要があるシナリオ（`arg`を`undefined`として渡すことが許可されないため、TypeScriptがエラーを発生させるなど）に役立ちます。

クエリ引数をundefinedにすることが許可されない場合、エラーが発生します。

useSomeQuery(arg, { skip: !!arg })

代わりにskipTokenを使用

useSomeQuery(arg ?? skipToken)

クエリまたはミューテーションセレクタに直接渡された場合、そのセレクタは常に初期化されていない状態を返します。

skipTokenを使用したTypeScriptでのクエリのスキップも参照してください。

useMutation

useMutationフックへのアクセス

const useMutationResult = api.endpoints.updatePost.useMutation(options)
// or
const useMutationResult = api.useUpdatePostMutation(options)

シグネチャ

type UseMutation = (
  options?: UseMutationStateOptions,
) => [UseMutationTrigger, UseMutationResult | SelectedUseMutationResult]

type UseMutationStateOptions = {
  // A method to determine the contents of `UseMutationResult`
  selectFromResult?: (result: UseMutationStateDefaultResult) => any
  // A string used to enable shared results across hook instances which have the same key
  fixedCacheKey?: string
}

type UseMutationTrigger<T> = (arg: any) => Promise<
  { data: T } | { error: BaseQueryError | SerializedError }
> & {
  requestId: string // A string generated by RTK Query
  abort: () => void // A method to cancel the mutation promise
  unwrap: () => Promise<T> // A method to unwrap the mutation call and provide the raw response/error
  reset: () => void // A method to manually unsubscribe from the mutation call and reset the result to the uninitialized state
}

type UseMutationResult<T> = {
  // Base query state
  originalArgs?: unknown // Arguments passed to the latest mutation call. Not available if using the `fixedCacheKey` option
  data?: T // Returned result if present
  error?: unknown // Error result if present
  endpointName?: string // The name of the given endpoint for the mutation
  fulfilledTimestamp?: number // Timestamp for when the mutation was completed

  // Derived request status booleans
  isUninitialized: boolean // Mutation has not been fired yet
  isLoading: boolean // Mutation has been fired and is awaiting a response
  isSuccess: boolean // Mutation has data from a successful call
  isError: boolean // Mutation is currently in an "error" state
  startedTimeStamp?: number // Timestamp for when the latest mutation was initiated

  reset: () => void // A method to manually unsubscribe from the mutation call and reset the result to the uninitialized state
}

ヒント

生成された`useMutation`フックは、トリガーコールバックが実行された後、結果のプロパティに影響を与えるため、デフォルトでコンポーネントを再レンダリングします。トリガーを呼び出したいが、フックを使用して結果をサブスクライブする必要がない場合は、`selectFromResult`オプションを使用して、フックが重視するプロパティを制限できます。

完全に空のオブジェクトを返すということは、個々のミューテーション呼び出しは多くても1回しか再レンダリングされないことを意味します。例：

selectFromResult: () => ({})

• パラメータ

  • options：フックのサブスクリプション動作を制御するオプションのセット
    • selectFromResult：タプル内の2番目のアイテムとして返されるミューテーション結果をカスタマイズするために使用できるコールバック
    • fixedCacheKey：フックインスタンス間で共有結果を有効にするために使用されるオプションの文字列

• 戻り値：以下のものを含むタプル

  • trigger：提供された引数に基づいてデータの更新をトリガーする関数。トリガー関数は、上記の特性を持つプロミスを返し、プロミスの動作を処理するために使用できます。
  • mutationState：現在の読み込み状態と要求に関するメタデータを含むクエリステータスオブジェクト、または該当する場合は`selectFromResult`オプションによって返される値。さらに、このオブジェクトには以下が含まれます。
    • フックを元の状態にリセットし、キャッシュから現在の結果を削除する`reset`メソッド。
    • `trigger`関数の最後の呼び出しに渡された引数を格納する`originalArgs`プロパティ。

説明

特定のエンドポイントの更新要求をトリガーし、コンポーネントをサブスクライブしてReduxストアから要求ステータスを読み取るReactフック。読み込みステータスが変更されると、コンポーネントは再レンダリングされます。

機能

• サーバー上のデータの変更またはキャッシュの無効化をトリガーする要求の発火を手動で制御
• コンポーネントをサブスクライブしてキャッシュされたデータをストアに保持し、コンポーネントがアンマウントされるとサブスクライブを解除します。
• Reduxストアから最新の要求ステータスとキャッシュされたデータを取得します。
• 要求ステータスが変更され、データが利用可能になると再レンダリングされます。

useQueryState

useQueryフックへのアクセス

const useQueryStateResult = api.endpoints.getPosts.useQueryState(arg, options)

シグネチャ

type UseQueryState = (
  arg: any | SkipToken,
  options?: UseQueryStateOptions,
) => UseQueryStateResult | SelectedQueryStateResult

type UseQueryStateOptions = {
  skip?: boolean
  selectFromResult?: (result: UseQueryStateDefaultResult) => any
}

type UseQueryStateResult<T> = {
  // Base query state
  originalArgs?: unknown // Arguments passed to the query
  data?: T // The latest returned result regardless of hook arg, if present
  currentData?: T // The latest returned result for the current hook arg, if present
  error?: unknown // Error result if present
  requestId?: string // A string generated by RTK Query
  endpointName?: string // The name of the given endpoint for the query
  startedTimeStamp?: number // Timestamp for when the query was initiated
  fulfilledTimeStamp?: number // Timestamp for when the query was completed

  isUninitialized: false // Query has not started yet.
  isLoading: false // Query is currently loading for the first time. No data yet.
  isFetching: false // Query is currently fetching, but might have data from an earlier request.
  isSuccess: false // Query has data from a successful load.
  isError: false // Query is currently in an "error" state.
}

• パラメータ

  • arg: エンドポイントで定義されたクエリに渡される引数。skipTokenもここで渡すことができ、セレクションをスキップする別の方法として使用できます。skipTokenを参照してください。
  • options: フックの戻り値を制御するオプションのセット

• 戻り値

  • 現在の読み込み状態、API呼び出しから返された実際のデータまたはエラー、およびリクエストに関するメタデータを含むクエリ結果オブジェクト。selectFromResultでカスタマイズできます。

説明

Reduxストアからリクエストステータスとキャッシュされたデータを読み取るReactフック。読み込みステータスが変化し、データが利用可能になると、コンポーネントは再レンダリングされます。

このフックは新しいデータのフェッチをトリガーしません。そのユースケースについては、useQueryまたはuseQuerySubscriptionを参照してください。

機能

• Reduxストアから最新の要求ステータスとキャッシュされたデータを取得します。
• 要求ステータスが変更され、データが利用可能になると再レンダリングされます。

useQuerySubscription

useQuerySubscriptionフックへのアクセス

const { refetch } = api.endpoints.getPosts.useQuerySubscription(arg, options)

シグネチャ

type UseQuerySubscription = (
  arg: any | SkipToken,
  options?: UseQuerySubscriptionOptions,
) => UseQuerySubscriptionResult

type UseQuerySubscriptionOptions = {
  skip?: boolean
  refetchOnMountOrArgChange?: boolean | number
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
}

type UseQuerySubscriptionResult = {
  refetch: () => void // A function to force refetch the query
}

• パラメータ

  • arg: エンドポイントで定義されたクエリに渡される引数。skipTokenもここで渡すことができ、クエリをスキップする別の方法として使用できます。skipTokenを参照してください。
  • options: フックのフェッチ動作を制御するオプションのセット

• 戻り値

  • データをrefetchするための関数を含むオブジェクト

説明

エンドポイントからデータのフェッチを自動的にトリガーし、コンポーネントをキャッシュされたデータに「サブスクライブ」するReactフック。

クエリ引数はキャッシュキーとして使用されます。クエリ引数を変更すると、フックは、キャッシュに存在しない場合にデータの再フェッチを実行します。

このフックは、リクエストステータスまたはキャッシュされたデータを返しません。そのユースケースについては、useQueryまたはuseQueryStateを参照してください。

機能

• フック引数とキャッシュされたデータの存在に基づいて、データを取得するための要求を自動的にトリガーします。
• コンポーネントをサブスクライブしてキャッシュされたデータをストアに保持し、コンポーネントがアンマウントされるとサブスクライブを解除します。
• 対応する基準が満たされたときに自動再フェッチをトリガーするためのポーリング/再フェッチオプションを受け入れます。

useLazyQuery

useLazyQueryフックへのアクセス

const [trigger, result, lastPromiseInfo] =
  api.endpoints.getPosts.useLazyQuery(options)
// or
const [trigger, result, lastPromiseInfo] = api.useLazyGetPostsQuery(options)

シグネチャ

type UseLazyQuery = (
  options?: UseLazyQueryOptions
) => [UseLazyQueryTrigger, UseQueryStateResult, UseLazyQueryLastPromiseInfo]

type UseLazyQueryOptions = {
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
  selectFromResult?: (result: UseQueryStateDefaultResult) => any
}

type UseLazyQueryTrigger<T> = (arg: any, preferCacheValue?: boolean) => Promise<
  QueryResultSelectorResult
> & {
  arg: unknown // Whatever argument was provided to the query
  requestId: string // A string generated by RTK Query
  subscriptionOptions: SubscriptionOptions // The values used for the query subscription
  abort: () => void // A method to cancel the query promise
  unwrap: () => Promise<T> // A method to unwrap the query call and provide the raw response/error
  unsubscribe: () => void // A method used to manually unsubscribe from the query results
  refetch: () => void // A method used to re-run the query. In most cases when using a lazy query, you will never use this and should prefer to call the trigger again.
  updateSubscriptionOptions: (options: SubscriptionOptions) () => void // A method used to update the subscription options (eg. pollingInterval)
}

type UseQueryStateResult<T> = {
  // Base query state
  originalArgs?: unknown // Arguments passed to the query
  data?: T // The latest returned result regardless of trigger arg, if present
  currentData?: T // The latest returned result for the trigger arg, if present
  error?: unknown // Error result if present
  requestId?: string // A string generated by RTK Query
  endpointName?: string // The name of the given endpoint for the query
  startedTimeStamp?: number // Timestamp for when the query was initiated
  fulfilledTimeStamp?: number // Timestamp for when the query was completed

  isUninitialized: false // Query has not started yet.
  isLoading: false // Query is currently loading for the first time. No data yet.
  isFetching: false // Query is currently fetching, but might have data from an earlier request.
  isSuccess: false // Query has data from a successful load.
  isError: false // Query is currently in an "error" state.
}

type UseLazyQueryLastPromiseInfo = {
  lastArg: any
}

• パラメータ

  • options: フックのフェッチ動作と返される結果値を制御するオプションのセット。フェッチ動作に影響を与えるオプションは、遅延クエリが少なくとも1回トリガーされた後にのみ有効になります。

• 戻り値：以下のものを含むタプル

  • trigger: 呼び出されると、エンドポイントに対応するデータを取得する関数
  • result: 現在の読み込み状態、API呼び出しから返された実際のデータまたはエラー、およびリクエストに関するメタデータを含むクエリ結果オブジェクト。selectFromResultでカスタマイズできます。
  • lastPromiseInfo: trigger関数を呼び出すために使用された最後の引数を含むオブジェクト

説明

useQueryと似ていますが、データフェッチのタイミングを手動で制御できるReactフック。

このフックには、useLazyQuerySubscriptionの機能が含まれています。

機能

• データを取得するためのリクエストの発火を手動で制御
• コンポーネントをサブスクライブしてキャッシュされたデータをストアに保持し、コンポーネントがアンマウントされるとサブスクライブを解除します。
• Reduxストアから最新の要求ステータスとキャッシュされたデータを取得します。
• 要求ステータスが変更され、データが利用可能になると再レンダリングされます。
• 対応する条件が満たされ、フェッチが少なくとも1回手動で呼び出された場合に、自動的な再フェッチをトリガーするためのポーリング/再フェッチオプションを受け入れます。

注記

LazyQueryから返されたtrigger関数が呼び出されると、キャッシュされたデータが存在する場合でも、常にサーバーへの新しいリクエストを開始します。キャッシュされた値が存在する場合は、それをすぐに返す場合は、preferCacheValue（関数の2番目の引数）をtrueに設定します。

useLazyQuerySubscription

useLazyQuerySubscriptionフックへのアクセス

const [trigger, lastArg] =
  api.endpoints.getPosts.useLazyQuerySubscription(options)

シグネチャ

type UseLazyQuerySubscription = (
  options?: UseLazyQuerySubscriptionOptions,
) => [UseLazyQuerySubscriptionTrigger, LastArg]

type UseLazyQuerySubscriptionOptions = {
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
}

type UseLazyQuerySubscriptionTrigger = (
  arg: any,
  preferCacheValue?: boolean,
) => void

• パラメータ

  • options: フックのフェッチ動作を制御するオプションのセット。オプションは、遅延クエリが少なくとも1回トリガーされた後にのみ有効になります。

• 戻り値：以下のものを含むタプル

  • trigger: 呼び出されると、エンドポイントに対応するデータを取得する関数
  • lastArg: trigger関数を呼び出すために使用された最後の引数

説明

useQuerySubscriptionと似ていますが、データフェッチのタイミングを手動で制御できるReactフック。

このフックは、リクエストステータスまたはキャッシュされたデータを返しません。そのユースケースについては、useLazyQueryを参照してください。

機能

• データを取得するためのリクエストの発火を手動で制御
• コンポーネントをサブスクライブしてキャッシュされたデータをストアに保持し、コンポーネントがアンマウントされるとサブスクライブを解除します。
• 対応する条件が満たされ、フェッチが少なくとも1回手動で呼び出された場合に、自動的な再フェッチをトリガーするためのポーリング/再フェッチオプションを受け入れます。

usePrefetch

usePrefetchフックへのアクセス

const prefetchCallback = api.usePrefetch(endpointName, options)

シグネチャ

type UsePrefetch = (
  endpointName: string,
  options?: UsePrefetchOptions,
) => PrefetchCallback

type UsePrefetchOptions =
  | {
      // If specified, only runs the query if the difference between `new Date()` and the last
      // `fulfilledTimeStamp` is greater than the given value (in seconds)
      ifOlderThan?: false | number
    }
  | {
      // If `force: true`, it will ignore the `ifOlderThan` value if it is set and the query
      // will be run even if it exists in the cache.
      force?: boolean
    }

type PrefetchCallback = (arg: any, options?: UsePrefetchOptions) => void

• パラメータ

  • endpointName: データをプリフェッチするエンドポイントの名前
  • options: プリフェッチリクエストが発生するかどうかを制御するオプションのセット

• 戻り値

  • 呼び出されると、指定されたエンドポイントのデータのフェッチを開始するprefetchコールバック

説明

事前にデータのフェッチを開始するために使用できるReactフック。

機能

• データを取得するためのリクエストの発火を手動で制御