React はじめに

バージョン4.4.0.0から、DEXTUploadX5（以下 X5）は React 環境をサポートします。 React で X5 を使用するには、dextuploadx5-react パッケージを使用します。

この文書では、Node.js と Webpack ベースの環境を基準として、クライアントとサーバーが分離された構成で X5 のリスト型 UI がブラウザに生成されるまでの最小構成を説明します。実際のプロジェクトでは、ディレクトリ構成、ルーティング方式、配布方式が異なる場合があるため、ここでは特定のサンプル構成に依存しない共通概念と必須設定のみを扱います。

パッケージの役割

dextuploadx5-react: React で X5 を利用するための Provider、UI コンポーネント、制御オブジェクトを提供します。
dextuploadx5-react-webpack: Webpack 環境で X5 静的リソースをプロジェクトの静的パスに配置しやすくする補助パッケージです。
dextuploadx5-express-handler: Express サーバーで X5 のアップロード要求を処理する際に使用するサーバー側ハンドラーパッケージです。

この文書では、リスト型 UI を画面に表示するところまでを説明します。実際のアップロード・ダウンロード処理や dextuploadx5-express-handler の使い方は別文書で扱います。

パッケージのインストール

クライアントとサーバーが別プロジェクトであれば、それぞれに必要なパッケージだけをインストールすればよいです。（サーバーに必要なパッケージは React > アップロード文書を参照してください。）

# クライアントプロジェクト
npm install react react-dom dextuploadx5-react
npm install -D html-webpack-plugin dextuploadx5-react-webpack

X5 静的リソースの配置

ブラウザは X5 の動作に必要なスクリプトとリソースを productPath を基準に読み込みます。そのため、このパスの下に実際の X5 製品ファイルが配置されている必要があります。

Webpack 環境では、dextuploadx5-react-webpack を使用すると静的リソースの配置を簡単にできます。

# webpack.config.js の例

import path from "path";
import { withDEXTUploadX5 } from "dextuploadx5-react-webpack";

const config = {
  entry: "./src/index.jsx",
  output: {
    publicPath: "/"
  }
};

// withDEXTUploadX5 を使うと静的リソース配置を自動で処理します。
export default withDEXTUploadX5(config, {
  publicDir: path.resolve("public"),
  dx5DirName: "dx5"
});

上記のように設定すると、通常ブラウザは /dx5/ パスで X5 リソースにアクセスします。

補助パッケージを使わない場合は、node_modules/dextuploadx5-react/dist/dx5 ディレクトリをアプリケーションの静的ファイルパスに直接コピーする必要があります。

認証キーと productPath の設定

X5 コンポーネントを使用するには、子 X5 UI コンポーネントを使用するコンポーネントを DEXTUploadX5Provider で囲み、 DEXTUploadX5Provider に認証キーと productPath を設定します。

import { useEffect, useState } from "react";
import { DEXTUploadX5Provider } from "dextuploadx5-react";

export default function App() {
  return (
    <DEXTUploadX5Provider
      authKey="jn+xziPdVh6f5KN17uFH... skip ...WiXAyO2FdI9r5XGfwxQ="
      productPath="/dx5/"
    >
      <UploadPage />
    </DEXTUploadX5Provider>
  );
}

認証キーと productPath の値はクライアントコードに直接記述することも、サーバー API から取得して適用することもできます。運用環境で認証キーをサーバー側で管理するなら、API 方式の方が一般的です。

# Express サーバーで設定を提供する例
import express from "express";

const router = express.Router();

router.get("/api/dx5-config", (req, res) => {
  res.json({
    authKey: process.env.DX5_AUTHKEY,
    productPath: process.env.DX5_PRODUCT_PATH || "/dx5/"
  });
});

export default router;

# React で設定取得後に Provider を適用する例
import { useEffect, useState } from "react";
import { DEXTUploadX5Provider } from "dextuploadx5-react";

export default function App() {
  const [config, setConfig] = useState(null);

  useEffect(() => {
    fetch("/api/dx5-config")
      .then((res) => res.json())
      .then((data) => setConfig(data));
  }, []);

  if (!config) return null;

  return (
    <DEXTUploadX5Provider
      authKey={config.authKey}
      productPath={config.productPath || "/dx5/"}
    >
      <UploadPage />
    </DEXTUploadX5Provider>
  );
}

productPath と実際の静的ファイル配置パスが一致しない場合、コンポーネントは正常に生成されません。

リスト型 UI の生成

リスト型のアップロード UI を作成するには、DEXTUploadX5List をレンダリングします。表示サイズを指定し、生成完了時点とエラーを確認するコールバックを接続するのが一般的です。

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);
    setVersion(dx.getVersion());
  };

  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>
    </div>
  );
}

コンポーネント生成後は、DX5.get("dext5") のようにオブジェクトを取得し、ファイル選択、アップロード、リスト制御などの動作を接続できます。ただし、この文書では画面生成までのみを扱います。

実行確認

次の条件がすべて満たされると、React 画面で X5 のリスト型 UI が生成されます。

ブラウザが productPath パスの X5 リソースを正常に読み込めること。
認証キーが有効に渡されること。
DEXTUploadX5Provider が DEXTUploadX5List の上位に配置されていること。
クライアントとサーバー間の API 通信が遮断されていないこと。

画面に X5 リスト領域が表示され、onCreated コールバックでバージョン情報が確認できれば、 React 環境での基本初期化は完了です。

次の段階

ここまでは React 画面に X5 コンポーネントを生成する段階です。実際のファイルアップロードとダウンロードを処理するには、サーバー側処理 URL、応答形式、保存パス、エラー処理ルールを追加で合わせる必要があります。

アップロード構成は React > アップロード文書を参照してください。
ダウンロード構成は React > ダウンロード文書を参照してください。