Skip to main content
Version: v3

Unified upload strategy

strategy type

use hook

alova@3.3+

Before using extended hooks, make sure you are familiar with the basic use of alova.

Simple file upload, base64, file object, blob object, arraybuffer object, Canvas can be directly uploaded.

Use scenarios include:

  1. Only one upload button

  2. The style of the upload component does not match

  3. The upload data format is diverse

Features​

  1. Automatic conversion of multiple formats

  2. Support single file and batch upload

  3. Get the upload progress and total progress of each file

  4. Limit file format and size

  5. Automatic preview thumbnail

Usage​

Basic usage​

<template>
  <button @click="handleUpload">Upload</button>
  <div>Total progress: {{ progress.uploaded / progress.total * 100 }}</div>
  <div>Success number: {{ successCount }}, failure number: {{ failCount }}</div>
  <div v-for="fileItem in fileList">
    <img :src="fileItem.src" />
    <span v-if="fileItem.status === 1"
      >Upload progress: {{ fileItem.progress.uploaded / fileItem.progress.total * 100 }}</span
    >
    <span v-else-if="fileItem.status === 3">{{ fileItem.error.message }}</span>
  </div>
</template>

<script setup>
  const {
    // File data list, each item contains file name, file path, upload status, upload progress, for specific format, see "Upload file data"
    fileList,

    // The first file data item, generally used to upload a single file
    file,

    // Is it uploading
    uploading,

    // Upload error message
    error,

    // Number of successful uploads
    successCount,

    // Number of failed uploads
    failCount,

    // Total upload progress, including uploaded and total
    progress,

    // Add file data items, automatically converted to File objects after adding
    appendFiles,

    // Delete files
    removeFiles,

    // Trigger upload
    upload,

    // Cancel upload
    abort,

    // Each file upload success event
    onSuccess,

    // Each file upload failure event
    onError,

    // Each file upload completion event
    onComplete
  } = useUploader(({ file, name }) => uploadFile(file, name));

  const handleUpload = async () => {
    await appendFiles();
    await upload();
  };
</script>

Append uploading files​

appendFiles allows you to append files to the upload list by passing in base64, File object, Blob, ArrayBuffer, HTMLCanvasElement data formats, and automatically convert them into a unified File object. The following demonstrates its usage through specific scenarios.

Append a single File object​

// Create an object through new File, the name field is used to identify the file name
const file = {
  file: new File(['file content'], 'report.pdf', { type: 'application/pdf' })
};

// Call appendFiles, if start is not passed, it will be appended to the end of the list by default
const appendCount = await appendFiles(file);

Batch append file data in multiple formats​

Append base64 images, Blob data and Canvas screenshots at the same time.

// Base64 image (name and mimeType are required)
const base64File = {
  file: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...',
  name: 'chart.png', // defaults to image.png
  mimeType: 'image/png' // defaults to the base64 data prefix
};

// Blob data (such as obtained from the clipboard)
const blob = new Blob(
  [
    JSON.stringify({
      data: 'test'
    })
  ],
  {
    type: 'application/json'
  }
);
const blobFile = {
  file: blob,
  name: 'config.json', // defaults to file
  mimeType: 'application/json' // defaults to blob.type
};

// Canvas
const canvas = document.querySelector('canvas');
const canvasFile = {
  file: canvas,
  name: 'screenshot.png', // defaults to image.png
  mimeType: 'image/png' // defaults to blob.type
};

// Batch append files
const appendCount = await appendFiles([base64File, blobFile, canvasFile]);

Insert to the specified position​

Insert the newly uploaded file into the second position of the list.

// Insert a CSV file
const insertFile = {
  file: new File(['id,name\n1,John'], 'data.csv', { type: 'text/csv' })
};

// Insert the file to position 2 (index starts at 0)
const appendCount = await appendFiles(insertFile, {
  start: 2
});

Select file​

When no file data is passed, the upload dialog box will be opened by default to select the file.

// Append files through appendFiles
const appendCount = await appendFiles({
  // Upload file type, this parameter will be set to the accept attribute of <input type="file">
  // See [https://developer.mozilla.org/docs/Web/HTML/Reference/Elements/input/file#accept]
  accept: 'png, jpg, jpeg',

  // Whether to allow multiple files to be selected, this parameter will be set to the multiple attribute of <input type="file">
  // See [https://developer.mozilla.org/docs/Web/HTML/Element/input/file#multiple]
  multiple: true,

  // Insert to the start of the list
  start: 0
});

Trigger upload​

The upload function is used to trigger the file upload process, supporting uploading all files or specified files.

Automatically upload all pending files​

Upload all "not uploaded" or "failed to upload" files in the upload list.

const response = await upload();

Specify specific files to upload​

Re-upload the files with indexes 1 and 3. If there are files that have been successfully uploaded, an error will be reported.

const response = await upload(1, 3);

You can also pass in the item specified in fileList to upload

const response = await upload(fileList[1], fileList[3]);

Limit the number of files​

Use limit to limit the number of uploaded files. The default is unlimited.

useUploader(({ file, name }) => uploadFile(file, name), {
  // Limit uploaded files
  limit: 3
});

Delete file items​

The removeFiles function can be used to delete file items in the upload list. The items being uploaded will be interrupted.

// Delete all items
removeFiles();
// Delete items with index 0 and 2
removeFiles(0, 2);

You can also pass in the items specified in fileList to delete

removeFiles(fileList[1], fileList[3]);

Interrupt upload​

The abort function can be used to interrupt the upload of file items in the list.

// Abort all items being uploaded
abort();
// Abort items with indexes 0 and 2
abort(0, 2);

You can also pass in the item specified in fileList to abort

abort(fileList[1], fileList[3]);

Upload file data​

When a file is added to the upload list via appendFiles, fileList and file will be updated, which contains relevant information about the uploaded file.

const {
  // Type is File[]
  fileList,

  // Type is File
  file
} = useUploader(({ file, name }) => uploadFile(file, name));

The information they contain is as follows:

interface File {
  // Temporary path or file path after successful upload, not image
  src?: string;

  // File object
  file: File;

  // 0 means not uploaded, 1 means uploading, 2 means completed, 3 means upload error
  status: 0 | 1 | 2 | 3;

  // Error object, when uploading error, error object needs to be assigned
  error?: Error;

  // Upload progress information
  progress: {
    uploaded: number;
    total: number;
  };
}

Batch upload​

By default, when calling upload to upload multiple files, the request handler function will be called in a loop, which is usually convenient when the interface only supports single file upload. But when the interface supports batch upload, you can enable batch upload by setting mode to batch. At this time, the request handler function will only be called once and get the array parameter.

useUploader(fileList => batchUpload(fileList), {
  mode: 'batch'
});

Image preview​

When uploading images and want to preview them, you can set localLink and replaceSrc.

useUploader(({ file, name }) => uploadFile(file, name), {
  // Generate a temporary image path, which can be used to display the image content before the image is uploaded. The default value is false
  localLink: true,

  // When the upload is successful, the src field in the fileList item can be automatically replaced with the file address on the server. It is often used when uploading images
  // data is the response data. This function returns the file address on the server
  // If this function is not specified, there will be no replacement behavior
  // index is the image index, which is often used when mode is `batch`
  replaceSrc: (data, index) => data.imgPath
});

Customize file selection​

As mentioned in appendFile, if files is not passed in, a dialog box will be opened to select the file. This default is valid on the browser side. When you use this request strategy in a non-browser environment, you can customize the file selection.

The following is an example of selecting an image in react-native.

useUploader.selectFile = async fileAppendOptions => {
  const { status } = await Permissions.askAsync(Permissions.CAMERA_ROLL);
  if (status !== 'granted') {
    throw new Error('Camera roll permission not granted');
  }

  const result = await ImagePicker.launchImageLibraryAsync({
    mediaTypes: ImagePicker.MediaTypeOptions.Images,
    allowsEditing: true,
    aspect: [4, 3],
    quality: 1
  });

  if (result.didCancel) {
    throw new Error('user canceled');
  }

  return result.assets.map(({ uri, type, name }) => ({
    file: uri,
    name: name || 'image.png',
    mimeType: type || 'image/png'
  }));
};

API​

Hook Configuration​

NameDescriptionTypeDefaultVersion
limitLimit the number of uploadsnumber-3.3.0
localLinkWhether to generate a local preview URLbooleanfalse3.3.0
replaceSrcReplace the file path with the response data(response: any, index: number) => string-3.3.0
modeUpload mode, single upload or batch upload'each' | 'batch''each'3.3.0

Responsive data​

NameDescriptionTypeVersion
fileListA list of file data, each item contains the file name, file path, upload status, and upload progressAlovaFileItem[]3.3.0
fileThe first file data item, generally used to upload a single fileAlovaFileItem | undefined3.3.0
uploadingIs uploading in progressboolean3.3.0
errorUpload error messageError | undefined3.3.0
progressTotal upload progress, including uploaded and totalProgress3.3.0
successCountNumber of successful uploadsnumber3.3.0
failCountNumber of failed uploadsnumber3.3.0

AlovaFileItem​

NameDescriptionTypeVersion
fileFile objectFile3.3.0
srcFile preview srcstring3.3.0
errorError object, with value when upload failsError | undefined3.3.0
status0 means not uploaded, 1 means uploading, 2 means completed, 3 means upload error0 | 1 | 2 | 33.3.0
progressCurrent file upload progressProgress3.3.0

Progress​

NameDescriptionTypeVersion
uploadedNumber of uploaded filesnumber3.3.0
totalTotalnumber3.3.0

Operation function​

NameDescriptionFunction parameterReturn valueVersion
appendFilesAdd file data item, automatically converted to File object after addingfile: AlovaRawFile | AlovaRawFile[], options?: FileAppendOptionsPromise<number>3.3.0
uploadUpload file...positions: Array<AlovaFileItem | number>Promise<Response>3.3.0
removeFilesDelete file data item...positions: Array<AlovaFileItem | number>void3.3.0
abortAbort file upload...positions: Array<AlovaFileItem | number>void3.3.0

AlovaRawFile​

NameDescriptionTypeVersion
fileFile object, base64, Blob, File, ArrayBuffer or HTMLCanvasElementFile | string | Blob | ArrayBuffer | HTMLCanvasElement3.3.0
srcFile preview srcstring?3.3.0
nameFile namestring?3.3.0
mimeTypeFile mimeTypestring?3.3.0

FileAppendOptions​

NameDescriptionTypeVersion
startInsert positionnumber?3.3.0
multipleWhether multiple selection is allowed, valid in file dialog boxboolean?3.3.0
acceptSelectable file suffix, valid in file dialog boxstring?3.3.0

Event​

NameDescriptionCallback parameterVersion
onSuccessUpload success eventevent3.3.0
onErrorUpload failure eventevent3.3.0
onCompleteUpload completion eventevent3.3.0
Is using alova in your project? please tell me!