React ダウンロード

この文書では、React 環境で DEXTUploadX5（以下 X5）のダウンロードを接続する基本フローを説明します。ダウンロードはアップロードと異なり、ブラウザにすでに存在するローカルファイルではなく、サーバーに保存されたファイル情報を X5 リストに関連付けた後で取得する方式で構成します。

ダウンロードの基本概念

React でダウンロードを処理する際の基本フローは次のとおりです。

ダウンロード対象ファイルの情報を取得します。
X5 コンポーネントに仮想ファイルとして登録します。
各仮想ファイルにダウンロード URL を関連付けます。
download() を呼び出します。
サーバーは対象ファイルを添付応答として返します。

つまり、ダウンロードではブラウザで実ファイルを先に選択するのではなく、サーバー側のファイル情報を UI に関連付ける工程が先に必要です。

仮想ファイルの登録

ダウンロード可能な項目は通常 addVirtualFile() または addVirtualFileList() で登録します。このとき、各項目には一意識別値、名前、サイズ、ダウンロード URL が含まれている必要があります。

const handleCreated = (id) => {
  const dx = DX5.get(id);

  dx.addVirtualFile({
    vindex: "FD0001",
    name: "sample-1.jpg",
    size: 509147,
    downUrl: "/api/download?key=FD0001"
  });

  dx.addVirtualFile({
    vindex: "FD0002",
    name: "sample-2.jpg",
    size: 239826,
    downUrl: "/api/download?key=FD0002"
  });
};

ダウンロード機能は、downUrl が関連付けられた仮想ファイルを基準に動作します。

ダウンロードの実行

仮想ファイル登録が完了したら、ボタンイベントなどから download() を呼び出して、単一ダウンロードまたは複数ダウンロードを実行できます。

const handleDownloadClick = (flag, multiple = false) => {
  DX5.get("dext5")?.download(flag, multiple);
};

最初の引数には対象範囲を指定するフラグを渡します。

AUTO: 基本対象基準
SELECTED: 選択項目基準
CHECKED: チェック項目基準

2 番目の引数に true を渡すと、複数ダウンロード方式で処理できます。

最も単純な例

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

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

  const handleCreated = (id) => {
    const dx = DX5.get(id);
    // X5 は既定で 100MB を超えるファイルをダウンロードできないため、
    // 必要に応じて setLimitMultiDownloadSize メソッドで許容サイズを変更する必要があります。
    dx.setLimitMultiDownloadSize(300 * 1024 * 1024);
    dx.addVirtualFile({ vindex: "FD0001", name: "sample-1.jpg", size: 509147, downUrl: "/api/download?key=FD0001" });
    dx.addVirtualFile({ vindex: "FD0002", name: "sample-2.jpg", size: 239826, downUrl: "/api/download?key=FD0002" });

    setVersion(dx.getVersion());
  };

  const handleDownloadClick = (flag, multiple = false) => {
    DX5.get("dext5")?.download(flag, multiple);
  };

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

  return (
    <div>
      <DEXTUploadX5List
        id="dext5"
        style={{ width: "100%", height: "320px" }}
        onCreated={handleCreated}
        onError={handleError}
      />
      <p>DEXTUploadX5 Version: {version}</p>
      <button disabled={!isLoaded} onClick={() => handleDownloadClick("AUTO")}>単一ファイルをダウンロード</button>
      <button disabled={!isLoaded} onClick={() => handleDownloadClick("AUTO", true)}>複数ファイルをダウンロード</button>
    </div>
  );
}

setLimitMultiDownloadSize メソッドは許容範囲を変更するだけであり、ブラウザ性能やネットワーク性能そのものを高めるものではありません。

サーバー応答条件

ダウンロード URL は最終的にファイルデータを返す必要があります。ブラウザがファイル保存動作として処理するためには、サーバーが Content-Disposition: attachment ヘッダーを含めるのが一般的です。

import express from "express";
import fs from "fs";
import path from "path";

const router = express.Router();

router.get("/api/download", (req, res) => {
  const filePath = path.resolve("files/sample-1.jpg");

  res.setHeader(
    "Content-Disposition",
    "attachment; filename*=UTF-8''sample-1.jpg"
  );
  res.setHeader("Content-Type", "image/jpeg");

  res.sendFile(filePath);
});

export default router;

実際のサービスでは、URL パラメータ、投稿番号、ファイルキーなどでファイルを特定し、権限チェック後にファイルを応答する構成が一般的です。

HEAD 要求の処理

ダウンロード方式によっては、サーバーが HEAD 要求も処理する必要があります。そのため、ダウンロードルートを構成する際には、GET だけでなく必要に応じて HEAD も許可しておくのが安全です。

router.get("/api/download", handleDownload);
router.head("/api/download", handleDownload);