Vue.js Cautions

This document summarizes only the points you should be careful about when using DEXTUploadX5 (hereinafter X5) in a Vue.js environment. Most issues occur when the Vue component lifecycle conflicts with the way X5 components are created dynamically.

Do not render components before installing the plugin

X5 Vue components load dextuploadx5.js through the loader provided by DEXTUploadX5Plugin. If you render a component before installing the plugin, the X5 instance cannot be created.

Call app.use(DEXTUploadX5Plugin, ...) when creating the application.

Be careful when changing props that recreate the instance

X5 is not a normal HTML element. It is a component dynamically created internally through dx5.create. Therefore, when some props change, the existing X5 instance is removed and created again.

The props that reload the X5 component are as follows.

• id
• type
• progressType
• path
• waitingTime
• lang

By contrast, changes to style, class, hidden, event handlers, and Grid columns are handled without recreating the instance.

Use kebab-case event names in templates

In Vue templates, event names should be written in kebab-case. For example, connect the upload completed event as @upload-completed.

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

Automatic button binding is not supported

In a Vue.js environment, automatic button binding may not work reliably. If the internal module reference used at binding time changes during rendering or updates, the button event may fire while the actual X5 module object is empty, which can cause errors.

Button binding props have been removed from the X5 Vue components.

Do not access refs before loading is complete

X5 components are loaded asynchronously, so the internal module is not immediately available just because the ref has been connected. If you need to use a ref, access the module after loading is complete by using the wait() function exposed by the component.

<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">Add files</button>
</template>

For simple control, it is clearer to obtain the object with DX5.get(id) after the @created event.

Be careful when reading item information inside delete events

If you call DX5.get(id).getItemById(...) again inside an asynchronous state update callback from a delete-related event, the item may already be deleted by that time and an error can occur.

Do not look up the required item information again inside the state update callback. Read it into a variable first when the event is received, and use that value.

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

Apply Grid column information in one way

If Grid column information is set both through the columns prop and the @created event, one setting may overwrite the other depending on the application order.

It is safer to apply Grid column definitions consistently in one way, without mixing the initial creation timing and later update timing.

Do not use it in SSR environments

The X5 runtime uses browser-only objects. Therefore, it must not be configured to run directly during server rendering, and should be rendered after it is mounted in the browser.