React Academy · レッスン

useMutationによるMutation

useMutationでAPIにデータをPOSTし、読み込み中・エラー状態を処理して、成功時にqueryを無効化します。

「useMutationによるMutation」はCoddyKit上の無料React Academyレッスンです。これはレッスン3/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはReact Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 React Academyコースには全4レッスンが含まれています。

ようこそ

このレッスンでは、useMutation を使って API にデータを送信し、読み込み状態とエラー状態を処理し、ミューテーションの成功後に stale なクエリを無効化します。

useMutation の基本

mutationFn を指定して useMutation を呼び出します。mutate 関数と状態プロパティが返されます。操作を実行するには mutate() を呼び出します。

import { useMutation } from '@tanstack/react-query';

const { mutate, isLoading, isError } = useMutation({
  mutationFn: (newPost) => fetch('/api/posts', {
    method: 'POST',
    body: JSON.stringify(newPost),
  }).then(r => r.json()),
});

mutate の呼び出し

イベントハンドラーから `mutate(variables)` を呼び出します。variables は最初の引数として mutationFn に渡されます。

<button onClick={() => mutate({ title: 'New Post' })}>
  Create Post
</button>

コールバック：onSuccess、onError、onSettled

useMutation にコールバックオプションを追加します。onSuccess はミューテーションの成功後に、onError は失敗時に、onSettled は成功・失敗の両方で実行されます（finally に似ています）。

useMutation({
  mutationFn: createPost,
  onSuccess: (data) => {
    console.log('Created:', data);
    navigate('/posts/' + data.id);
  },
  onError: (error) => {
    toast.error(error.message);
  },
})

ミューテーション後にクエリを無効化する

ミューテーションが成功したら、関連するクエリを無効化して React Query に最新のデータを再取得させます。onSuccess で queryClient.invalidateQueries を使用します。

import { useQueryClient } from '@tanstack/react-query';

const queryClient = useQueryClient();

const { mutate } = useMutation({
  mutationFn: createPost,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['posts'] });
  },
});

await 構文のための mutateAsync

`mutate` の代わりに `mutateAsync` を使うと、ミューテーションを await し、try/catch で処理できます。

const { mutateAsync } = useMutation({ mutationFn: createPost });

async function handleSubmit() {
  try {
    const post = await mutateAsync({ title: 'Draft' });
    navigate('/posts/' + post.id);
  } catch (err) {
    setError(err.message);
  }
}

ミューテーション中に送信を無効にする

ミューテーションの実行中は `isPending`（または `isLoading`）を使って送信ボタンを無効にします。

const { mutate, isPending } = useMutation({ mutationFn: saveItem });

<button onClick={() => mutate(item)} disabled={isPending}>
  {isPending ? 'Saving...' : 'Save'}
</button>

onMutate による楽観的な更新

onMutate を使うと、サーバーの応答前にキャッシュを楽観的に更新できます。onMutate が返す context を使って onError でロールバックします。

useMutation({
  mutationFn: likePost,
  onMutate: async (id) => {
    await queryClient.cancelQueries({ queryKey: ['posts'] });
    const prev = queryClient.getQueryData(['posts']);
    queryClient.setQueryData(['posts'], old => old.map(p =>
      p.id === id ? { ...p, likes: p.likes + 1 } : p));
    return { prev };
  },
  onError: (err, id, ctx) => queryClient.setQueryData(['posts'], ctx.prev),
  onSettled: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
})

ミューテーション状態のリセット

useMutation の `reset()` を呼び出して、ミューテーションの state（data、error、status）をクリアします。別の画面へ移動した後やフォームをクリアするときに便利です。

const { mutate, isError, reset } = useMutation({ /* ... */ });

{isError && (
  <>
    <p>Error!</p>
    <button onClick={reset}>Try Again</button>
  </>
)}

複数のミューテーションを並列実行する

mutate を複数回、並列に呼び出せます。各呼び出しは個別に追跡されます。並列ミューテーションには mutateAsync と Promise.all を使用します。

await Promise.all([
  mutateAsync({ id: 1, title: 'First' }),
  mutateAsync({ id: 2, title: 'Second' }),
]);

確認問題

ミューテーションの成功後、UI に最新のデータを確実に表示するには、どの方法が推奨されますか？

まとめ

useMutation は mutate、isPending、ライフサイクルコールバックを提供します。関連するクエリを無効化するには onSuccess を使用します。await ベースの処理には mutateAsync を使用します。ロールバックを伴う楽観的な更新には onMutate と onError を使用します。

次に学ぶこと

次のレッスン：**Infinite Scroll & Pagination with useInfiniteQuery** — ページ分割されたデータを取得し、シームレスに追加のページを読み込みます。

よくある質問

「useMutationによるMutation」レッスンは無料ですか？

はい。「useMutationによるMutation」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、React Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 React Academyコースには全4レッスンが含まれています。

「useMutationによるMutation」で何を学びますか？

useMutationでAPIにデータをPOSTし、読み込み中・エラー状態を処理して、成功時にqueryを無効化します。ブラウザで直接実行するハンズオンコードでReact Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

React Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのReact Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン3/4です。

「useMutationによるMutation」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このReact Academyレッスンでコードを書いて実行できますか？

はい。すべてのReact Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← React Academyに戻る