2025年9月9日日本語

ReactのuseFormStatusフックを使用した進捗推定と完了時間予測の実装方法を学び、データ量の多いアプリケーションのユーザー体験を向上させます。

React useFormStatus 進捗推定：完了時間の予測

React 18で導入されたReactのuseFormStatusフックは、フォーム送信のステータスに関する貴重な情報を提供します。これは直接的に進捗推定を提供するものではありませんが、そのプロパティや他の技術を活用して、実行に時間がかかる可能性のあるフォーム送信中にユーザーに有意義なフィードバックを提供できます。この記事では、useFormStatusを使用する際の進捗推定と完了時間予測の方法を探り、より魅力的でユーザーフレンドリーな体験を実現します。

`useFormStatus`の理解

進捗推定に入る前に、useFormStatusの目的を簡単に振り返ってみましょう。このフックは、actionプロップを利用する<form>要素内で使用されるように設計されています。以下のプロパティを含むオブジェクトを返します：

pending: フォームが現在送信中かどうかを示すブール値。
data: フォームで送信されたデータ（送信が成功した場合）。
method: フォーム送信に使用されたHTTPメソッド（例：「POST」、「GET」）。
action: フォームのactionプロップに渡された関数。
error: 送信が失敗した場合のエラーオブジェクト。

useFormStatusはフォームが送信中かどうかを教えてくれますが、特にaction関数が複雑または長時間の操作を含む場合、送信の進捗に関する直接的な情報は提供しません。

進捗推定の課題

中心的な課題は、action関数の実行がReactにとって不透明であるという事実にあります。私たちは本質的にプロセスのどの段階にあるのかを知ることができません。これは特にサーバーサイドの操作に当てはまります。しかし、この制約を克服するために様々な戦略を用いることができます。

進捗推定の戦略

以下に、それぞれにトレードオフがあるいくつかのアプローチを紹介します：

1. Server-Sent Events (SSE) または WebSockets

最も堅牢な解決策は、サーバーからクライアントに進捗更新をプッシュすることです。これは以下を使用して実現できます：

Server-Sent Events (SSE): サーバーからクライアントへの単一HTTP接続を介して更新をプッシュできる単方向（サーバーからクライアント）プロトコルです。SSEは、クライアントが更新を*受信*するだけでよい場合に理想的です。
WebSockets: クライアントとサーバー間に持続的な接続を提供する双方向通信プロトコルです。WebSocketsは、双方向のリアルタイム更新に適しています。

例 (SSE):

サーバーサイド (Node.js):

            const express = require('express');
const app = express();

app.get('/progress', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.flushHeaders();

  let progress = 0;
  const interval = setInterval(() => {
    progress += 10;
    if (progress > 100) {
      progress = 100;
      clearInterval(interval);
      res.write(`data: {"progress": ${progress}, "completed": true}\n\n`);
      res.end();
    } else {
      res.write(`data: {"progress": ${progress}, "completed": false}\n\n`);
    }
  }, 500); // Simulate progress update every 500ms
});

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

クライアントサイド (React):

            import React, { useState, useEffect } from 'react';

function MyComponent() {
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const eventSource = new EventSource('/progress');

    eventSource.onmessage = (event) => {
      const data = JSON.parse(event.data);
      setProgress(data.progress);

      if (data.completed) {
        eventSource.close();
      }
    };

    eventSource.onerror = (error) => {
      console.error('EventSource failed:', error);
      eventSource.close();
    };

    return () => {
      eventSource.close();
    };
  }, []);

  return (
    <div>
      <p>Progress: {progress}%</p>
    </div>
  );
}

export default MyComponent;

解説:

サーバーはSSE用の適切なヘッダーを設定します。
サーバーは進捗更新をdata:イベントとして送信します。各イベントはprogressとcompletedフラグを含むJSONオブジェクトです。
ReactコンポーネントはEventSourceを使用してこれらのイベントをリッスンします。
コンポーネントは受信したイベントに基づいて状態（progress）を更新します。

利点: 正確な進捗更新、リアルタイムのフィードバック。

欠点: サーバーサイドの変更が必要、より複雑な実装。

2. APIエンドポイントによるポーリング

SSEやWebSocketsを使用できない場合は、ポーリングを実装できます。クライアントは定期的にサーバーにリクエストを送信して、操作のステータスを確認します。

例:

サーバーサイド (Node.js):

            const express = require('express');
const app = express();

// Simulate a long-running task
let taskProgress = 0;
let taskId = null;

app.post('/start-task', (req, res) => {
  taskProgress = 0;
  taskId = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15); // Generate a unique task ID

  // Simulate background processing
  const interval = setInterval(() => {
    taskProgress += 10;
    if (taskProgress >= 100) {
      taskProgress = 100;
      clearInterval(interval);
    }
  }, 500);

  res.json({ taskId });
});

app.get('/task-status/:taskId', (req, res) => {
  if (req.params.taskId === taskId) {
    res.json({ progress: taskProgress });
  } else {
    res.status(404).json({ message: 'Task not found' });
  }
});

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

クライアントサイド (React):

            import React, { useState, useEffect } from 'react';

function MyComponent() {
  const [progress, setProgress] = useState(0);
  const [taskId, setTaskId] = useState(null);

  const startTask = async () => {
    const response = await fetch('/start-task', { method: 'POST' });
    const data = await response.json();
    setTaskId(data.taskId);
  };

  useEffect(() => {
    if (!taskId) return;

    const interval = setInterval(async () => {
      const response = await fetch(`/task-status/${taskId}`);
      const data = await response.json();
      setProgress(data.progress);

      if (data.progress === 100) {
        clearInterval(interval);
      }
    }, 1000); // Poll every 1 second

    return () => clearInterval(interval);
  }, [taskId]);

  return (
    <div>
      <button onClick={startTask} disabled={taskId !== null}>Start Task</button>
      {taskId && <p>Progress: {progress}%</p>}
    </div>
  );
}

export default MyComponent;

解説:

クライアントは/start-taskを呼び出してタスクを開始し、taskIdを受け取ります。
その後、クライアントは/task-status/:taskIdを定期的にポーリングして進捗状況を取得します。

利点: 比較的実装が簡単で、持続的な接続を必要としません。

欠点: SSE/WebSocketsよりも精度が低い可能性があり、ポーリング間隔による遅延が発生し、頻繁なリクエストによりサーバーに負荷がかかります。

3. 楽観的更新とヒューリスティクス

場合によっては、楽観的更新とヒューリスティクスを組み合わせて、妥当な推定値を提供することができます。例えば、ファイルをアップロードしている場合、クライアントサイドでアップロードされたバイト数を追跡し、総ファイルサイズに基づいて進捗を推定できます。

例 (ファイルアップロード):

            import React, { useState } from 'react';

function MyComponent() {
  const [progress, setProgress] = useState(0);
  const [file, setFile] = useState(null);

  const handleFileChange = (event) => {
    setFile(event.target.files[0]);
  };

  const handleSubmit = async (event) => {
    event.preventDefault();
    if (!file) return;

    const formData = new FormData();
    formData.append('file', file);

    try {
      const xhr = new XMLHttpRequest();
      xhr.upload.addEventListener('progress', (event) => {
        if (event.lengthComputable) {
          const percentage = Math.round((event.loaded * 100) / event.total);
          setProgress(percentage);
        }
      });

      xhr.open('POST', '/upload'); // Replace with your upload endpoint
      xhr.send(formData);

      xhr.onload = () => {
        if (xhr.status === 200) {
          console.log('Upload complete!');
        } else {
          console.error('Upload failed:', xhr.status);
        }
      };

      xhr.onerror = () => {
        console.error('Upload failed');
      };

    } catch (error) {
      console.error('Upload error:', error);
    }
  };

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <input type="file" onChange={handleFileChange} />
        <button type="submit" disabled={!file}>Upload</button>
      </form>
      <p>Progress: {progress}%</p>
    </div>
  );
}

export default MyComponent;

解説:

コンポーネントはXMLHttpRequestオブジェクトを使用してファイルをアップロードします。
xhr.uploadのprogressイベントリスナーを使用して、アップロードの進捗を追跡します。
イベントのloadedプロパティとtotalプロパティを使用して、完了率を計算します。

利点: クライアントサイドのみで完結し、即時のフィードバックを提供できます。

欠点: 精度はヒューリスティクスの信頼性に依存し、すべてのタイプの操作に適しているとは限りません。

4. アクションをより小さなステップに分割する

action関数が複数の異なるステップを実行する場合、各ステップの後にUIを更新して進捗を示すことができます。これには、更新を提供するためにaction関数を修正する必要があります。

例:

            import React, { useState } from 'react';

async function myAction(setProgress) {
  setProgress(10);
  await someAsyncOperation1();
  setProgress(40);
  await someAsyncOperation2();
  setProgress(70);
  await someAsyncOperation3();
  setProgress(100);
}

function MyComponent() {
  const [progress, setProgress] = useState(0);

  const handleSubmit = async () => {
    await myAction(setProgress);
  };

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <button type="submit">Submit</button>
      </form>
      <p>Progress: {progress}%</p>
    </div>
  );
}

export default MyComponent;

解説:

myAction関数はsetProgressコールバックを受け入れます。
実行中の様々な時点で進捗状態を更新します。

利点: 進捗更新を直接制御できます。

欠点: action関数を修正する必要があり、ステップが容易に分割できない場合は実装がより複雑になる可能性があります。

完了時間の予測

進捗更新が得られたら、それらを使用して残りの推定時間を予測できます。簡単なアプローチは、特定の進捗レベルに到達するまでにかかった時間を追跡し、それを外挿して合計時間を推定することです。

例 (簡易版):

            import React, { useState, useEffect, useRef } from 'react';

function MyComponent() {
  const [progress, setProgress] = useState(0);
  const [estimatedTimeRemaining, setEstimatedTimeRemaining] = useState(null);
  const startTimeRef = useRef(null);

  useEffect(() => {
    if (progress > 0 && startTimeRef.current === null) {
      startTimeRef.current = Date.now();
    }

    if (progress > 0) {
      const elapsedTime = Date.now() - startTimeRef.current;
      const estimatedTotalTime = (elapsedTime / progress) * 100;
      const remainingTime = estimatedTotalTime - elapsedTime;
      setEstimatedTimeRemaining(Math.max(0, remainingTime)); // Ensure non-negative
    }
  }, [progress]);

  // ... (rest of the component and progress updates as described in previous sections)

  return (
    <div>
      <p>Progress: {progress}%</p>
      {estimatedTimeRemaining !== null && (
        <p>Estimated Time Remaining: {Math.round(estimatedTimeRemaining / 1000)} seconds</p>
      )}
    </div>
  );
}

export default MyComponent;

解説:

進捗が最初に更新されたときの開始時刻を保存します。
経過時間を計算し、それを使用して合計時間を推定します。
推定合計時間から経過時間を引くことで、残り時間を計算します。

重要な考慮事項:

精度: これは*非常に*単純化された予測です。ネットワーク状況、サーバーの負荷、その他の要因が精度に大きく影響する可能性があります。複数の間隔で平均を取るなど、より洗練された技術で精度を向上させることができます。
視覚的フィードバック: 時間が*推定値*であることを明確に示します。範囲（例：「残り推定時間：5～10秒」）を表示すると、より現実的になります。
エッジケース: 初期の進捗が非常に遅いエッジケースを処理します。ゼロ除算や過度に大きな推定値を表示するのを避けてください。

`useFormStatus`と進捗推定の組み合わせ

useFormStatus自体は進捗情報を提供しませんが、そのpendingプロパティを使用して進捗インジケータを有効または無効にすることができます。例：

            import React, { useState } from 'react';
import { useFormStatus } from 'react-dom';

// ... (Progress estimation logic from previous examples)

function MyComponent() {
  const [progress, setProgress] = useState(0);
  const { pending } = useFormStatus();

  const handleSubmit = async (formData) => {
    // ... (Your form submission logic, including updates to progress)
  };

  return (
    <form action={handleSubmit}>
      <button type="submit" disabled={pending}>Submit</button>
      {pending && <p>Progress: {progress}%</p>}
    </form>
  );
}

この例では、進捗インジケータはフォームが保留中（つまり、useFormStatus.pendingがtrueの間）にのみ表示されます。

ベストプラクティスと考慮事項

精度を優先する: 実行される操作のタイプに適した進捗推定技術を選択します。SSE/WebSocketsは一般的に最も正確な結果を提供しますが、より単純なタスクにはヒューリスティクスで十分な場合があります。
明確な視覚的フィードバックを提供する: プログレスバー、スピナー、その他の視覚的な合図を使用して、操作が進行中であることを示します。進捗インジケータと、該当する場合は残り推定時間に明確にラベルを付けます。
エラーを適切に処理する: 操作中にエラーが発生した場合は、ユーザーに有益なエラーメッセージを表示します。進捗インジケータが特定のパーセンテージで停止したままにならないようにします。
パフォーマンスを最適化する: UIスレッドで計算コストの高い操作を実行すると、パフォーマンスに悪影響を及ぼす可能性があるため避けてください。Webワーカーや他の技術を使用して、作業をバックグラウンドスレッドにオフロードします。
アクセシビリティ: 進捗インジケータが障害を持つユーザーにもアクセス可能であることを確認します。ARIA属性を使用して、操作の進捗に関する意味情報を提供します。例えば、プログレスバーでaria-valuenow、aria-valuemin、aria-valuemaxを使用します。
ローカライゼーション: 残り推定時間を表示する際は、異なる時間形式や地域の好みに注意してください。date-fnsやmoment.jsのようなライブラリを使用して、ユーザーのロケールに合わせて時間を適切にフォーマットします。
国際化: エラーメッセージやその他のテキストは、複数の言語をサポートするために国際化する必要があります。i18nextのようなライブラリを使用して翻訳を管理します。

結論

ReactのuseFormStatusフックは直接的に進捗推定機能を提供しませんが、他の技術と組み合わせることで、フォーム送信中にユーザーに有意義なフィードバックを提供できます。SSE/WebSockets、ポーリング、楽観的更新、またはアクションを小さなステップに分割することによって、より魅力的でユーザーフレンドリーな体験を創り出すことができます。精度を優先し、明確な視覚的フィードバックを提供し、エラーを適切に処理し、パフォーマンスを最適化して、場所や背景に関わらずすべてのユーザーに肯定的な体験を保証することを忘れないでください。

React useFormStatus 進捗推定：完了時間の予測

useFormStatusの理解

進捗推定の課題

進捗推定の戦略

1. Server-Sent Events (SSE) または WebSockets

2. APIエンドポイントによるポーリング

3. 楽観的更新とヒューリスティクス

4. アクションをより小さなステップに分割する

完了時間の予測

useFormStatusと進捗推定の組み合わせ

ベストプラクティスと考慮事項

結論

さらなる探求

`useFormStatus`の理解

`useFormStatus`と進捗推定の組み合わせ