Vue.js 注意事項

この文書では、Vue.js 環境で DEXTUploadX5（以下 X5）を使用する際に注意すべき項目のみをまとめます。多くの問題は、Vue コンポーネントのライフサイクルと X5 の動的生成方式が衝突するときに発生します。

プラグインのインストール前にコンポーネントをレンダリングしない

X5 Vue コンポーネントは DEXTUploadX5Plugin が提供するローダーを使用して dextuploadx5.js を読み込みます。プラグインをインストールしない状態でコンポーネントをレンダリングすると、X5 インスタンスを生成できません。

アプリケーション生成時に app.use(DEXTUploadX5Plugin, ...) を先に呼び出してください。

インスタンスを再生成する prop の変更に注意

X5 は通常の HTML 要素ではなく、内部的に dx5.create によって動的に生成されるコンポーネントです。そのため、一部の prop が変更されると既存の X5 インスタンスが削除され、再生成されます。

X5 コンポーネントを再ロードする prop は次のとおりです。

id
type
progressType
path
waitingTime
lang

一方、style、class、hidden、イベントハンドラー、Grid の columns の変更は、インスタンスを再生成せずに処理されます。

テンプレートでは kebab-case のイベント名を使用

Vue テンプレートでは、イベント名を kebab-case で記述することを推奨します。たとえばアップロード完了イベントは @upload-completed で接続します。

<DEXTUploadX5List
  id="dext5"
  @created="handleCreated"
  @upload-completed="handleUploadCompleted"
  @download-completed="handleDownloadCompleted"
  @error="handleError"
/>

自動ボタンバインディング機能は未サポート

Vue.js 環境では、自動ボタンバインディングが安定して動作しない場合があります。レンダリングや更新の過程で、バインディング時点の内部モジュール参照が変わると、ボタンイベントは発生しても実際の X5 モジュールオブジェクトが空の状態になり、エラーが発生することがあります。

X5 Vue コンポーネントでは、ボタンバインディング用の props は削除されています。

ロード完了前に ref へアクセスしない

X5 コンポーネントは非同期でロードされるため、ref が接続されたからといってすぐに内部モジュールを使用できるわけではありません。 ref を使用する必要がある場合は、コンポーネントが提供する wait() 関数を使い、ロード完了後にアクセスしてください。

<script setup>
import { ref } from "vue";

const uploaderRef = ref(null);

async function openDialog() {
  const dx = await uploaderRef.value?.wait();
  dx?.openFileDialog();
}
</script>

<template>
  <DEXTUploadX5List ref="uploaderRef" id="dext5" />
  <button @click="openDialog">ファイル追加</button>
</template>

単純な制御であれば、@created イベントの後に DX5.get(id) でオブジェクトを取得する方法の方が明確です。

削除イベント内で項目情報を取得するタイミングに注意

削除関連イベントで、非同期の状態更新コールバック内から DX5.get(id).getItemById(...) を再度呼び出すと、その時点ではすでに項目が削除されているため、エラーが発生する場合があります。

必要な項目情報は、状態更新コールバック内で再取得せず、イベントを受け取った時点で先に変数へ取り出して使用してください。

function handleItemDeleting(id, itemId) {
  const item = DX5.get(id)?.getItemById(itemId);
  eventLog.value.push("Deleting: " + item?.name);
}

Grid の列情報は一つの方法で適用

Grid スタイルで列情報を columns prop と @created イベントの両方で設定すると、適用順序によって一方の設定がもう一方を上書きする場合があります。

Grid の列定義は一つの方法で一貫して適用し、初期生成時点とその後の更新時点を混在させない方が安全です。

SSR 環境で使用しない

X5 ランタイムはブラウザ専用オブジェクトを使用します。そのため、サーバーレンダリング中に直接実行されるように構成してはいけません。ブラウザでマウントされた後にレンダリングされるように処理してください。