React アップロード

この文書では、React 環境で DEXTUploadX5（以下 X5）のアップロードを接続する最小限の流れを説明します。はじめに文書で Provider の適用とコンポーネント生成が完了していることを前提とします。

説明は Node.js と Express サーバーを基準としていますが、重要なのは特定のフレームワークではなく、 X5 が呼び出すアップロード URL とサーバー応答ルールを一致させることです。

アップロードの基本フロー

React でアップロードを処理する際の基本フローは次のとおりです。

DEXTUploadX5List または他の X5 UI コンポーネントを生成します。
コンポーネント生成後にアップロード処理 URL を指定します。（後から設定しても問題ありません。）
ユーザーがファイルまたはフォルダーを追加します。
upload() を呼び出してサーバー送信を開始します。
サーバーはアップロードを処理し、HTTP 200 応答を返します。
クライアントは onUploadCompleted または onError で結果を処理します。

クライアントでアップロード URL を指定

アップロードを実行するには、まずコンポーネントにアップロード URL を知らせる必要があります。一般的には onCreated の時点でコンポーネントオブジェクトを取得し、URL を設定します。

import { useState } from "react";
import { DX5, DEXTUploadX5List } from "dextuploadx5-react";

export default function UploadPage() {
  const [version, setVersion] = useState("");

  const handleCreated = (id) => {
    const dx = DX5.get(id);
    dx.setUploadURL("/api/upload");
    setVersion(dx.getVersion());
  };

  const handleError = (id, code, msg) => {
    alert(id + " => " + code + "\n" + msg);
  };

  const handleUploadCompleted = (id, result) => {
    console.log(result);
  };

  return (
    <DEXTUploadX5List
      id="dext5"
      style={{ width: "100%", height: "320px" }}
      onCreated={handleCreated}
      onError={handleError}
      onUploadCompleted={handleUploadCompleted}
    />
  );
}

アップロード先アドレスは、コンポーネントが実際に呼び出すサーバーパスです。開発環境と運用環境でアドレス体系が異なる場合があるため、プロジェクト環境に合わせて管理してください。

ファイル追加とアップロード実行

コンポーネント生成後は、DX5.get(id) でオブジェクトを取得し、ファイル選択ダイアログを開いたり、アップロードを直接実行したりできます。

const handleAddFilesClick = () => DX5.get("dext5")?.openFileDialog();
const handleAddFolderClick = () => DX5.get("dext5")?.openFolderDialog();
const handleUploadClick = () => DX5.get("dext5")?.upload("AUTO");

upload("AUTO") は、現在リストに追加されている項目を基準にアップロードを開始します。実際のサービスでは、ボタンイベント、フォーム送信イベント、保存ボタンなどに接続する方式が一般的です。

最も単純な例

import { useState } from "react";
import { DX5, DEXTUploadX5List } from "dextuploadx5-react";

export default function UploadPage() {
  const [version, setVersion] = useState("");
  const isLoaded = version !== "";

  const handleAddFilesClick = () => DX5.get("dext5")?.openFileDialog();
  const handleAddFolderClick = () => DX5.get("dext5")?.openFolderDialog();
  const handleUploadClick = () => DX5.get("dext5")?.upload("AUTO");

  const handleCreated = (id) => {
    const dx = DX5.get(id);
    dx.setUploadURL("/api/upload");
    setVersion(dx.getVersion());
  };

  const handleUploadCompleted = (id, result) => {
    alert("アップロードが完了しました。");
  };

  const handleError = (id, code, msg) => {
    alert(id + " => " + code + "\n" + msg);
  };

  return (
    <div>
      <DEXTUploadX5List
        id="dext5"
        style={{ width: "100%", height: "320px" }}
        onCreated={handleCreated}
        onError={handleError}
        onUploadCompleted={handleUploadCompleted}
      />
      <p>DEXTUploadX5 Version: {version}</p>
      <button disabled={!isLoaded} onClick={handleAddFilesClick}>ファイル追加</button>
      <button disabled={!isLoaded} onClick={handleAddFolderClick}>フォルダー追加</button>
      <button disabled={!isLoaded} onClick={handleUploadClick}>アップロード</button>
    </div>
  );
}

Express サーバー処理

Express 環境では、dextuploadx5-express-handler を利用して X5 のアップロード要求を処理できます。

# サーバープロジェクト
npm install express dextuploadx5-express-handler

import express from "express";
import { createDEXTUploadX5Handler } from "dextuploadx5-express-handler";

const router = express.Router();

router.post("/api/upload", createDEXTUploadX5Handler({
  // 最終的にファイルが保存される場所
  uploadDir: process.env.DEXT_UPLOAD_DIR,
  // 一時ファイルが保存される場所
  tempDir: process.env.DEXT_TEMP_DIR,
  // 一時ファイル保存後に呼び出されるハンドラー
  onComplete: async ({ res, files }) => {
    const results = [];

    for (const file of files) {
      // tempDir から uploadDir へファイルを移動またはコピーします。
      const saved = await file.save();
      results.push(saved.name);
    }

    res.status(200).type("text/plain; charset=utf-8").send(results.join("\n"));
  }
}));

export default router;

上記の例のように、最終処理時点で保存場所を決定し、必要な応答データを直接返すことができます。実際のサービスでは、ファイル識別値、保存パス、掲示物連携情報などを一緒に応答する場合が多いです。

サーバー応答ルール

X5 はアップロード要求が正常に完了したかどうかを HTTP ステータスコードで判断します。サーバーでアップロードが成功した場合は、200 応答を返す必要があります。

逆に、サーバー内部エラー、検証失敗、権限問題などがある場合は、状況に応じた 4xx または 5xx ステータスコードを返す必要があります。

サーバーでエラーが発生しているのに 200 で応答すると、X5 はアップロードが成功したと判断する場合があります。