react-upload-file

2.0.0-beta.6 • Public • Published

react-upload-file

NPM version NPM monthly downloads NPM total downloads Dependencies Status Build Status License Code Climate Test Coverage

Maybe the Best File Upload Component for React

Ready for production usage! Migrate to v2 now since v1 has many bugs and is deprecated.

Index

Catalog

Introduce

A Structure-Only, UI-Customizable and Modern file upload component for React which support IE10+ and basically support IE9, requiring node4+.

Installation

npm install react-upload-file -S

Best Practices

  • It's recommened to use arrow function to avoid 'this' problems.
  • Queries in baseUrl will be ignored if query is set.

API

Basic Options

options: {
  baseUrl: 'xxx',
  ...
}

options is an attribute of ReactUploadFile. The properties of options are:

name type default note
baseUrl String '' url
query Object/Function undefined Queries that appended after baseUrl. When it is a function, use its return value
body Object/Function undefined Key-values that need to add to formData besides files. When it is a function, use its return value
dataType String 'json' Accept type of response(json or text)
timeout Number 0 Timeout of the request. Callback function uploadError will be triggered and an object { type: 'TIMEOUTERROR', message: 'timeout' } will be returned as the argument. Default to 0 meaning no limit
accept String undefined Limit the type of file
multiple Boolean false Allow multi-upload or not
numberLimit Number 0 Limit how many files can be uploaded a time, 0 means no limit.
fileFieldName String/Function undefined Determine the field name of file. If it is a function, which will receive each file object as argument, use its return value. Default to file's name
withCredentials Boolean false Same as 'xhr.withCredentials'
requestHeaders Object undefined Key-values that will be set using 'xhr.setRequestHeader(key, value)'
userAgent String window.navigator.userAgent Used to set the userAgent string with serverside rendering isomorphic applications(required when rendering on the server)

Life Circle Functions

Also set as the properties of options.

beforeChoose()

Triggered immediately after clicking the chooseFileButton but before didChoose. Return true to continue or false to stop choosing.

@param null

@return {Boolean} Determine whether to continue uploading

didChoose(files)

The callback triggered after choosing.

@param filelist {Filelist} The array contains files.

@return your return

beforeUpload(files)

Triggered before uploading. Return true to continue or false to stop uploading.

@param files {Filelist} The array contains files.

@return {Boolean} Allow the upload action or not.

didUpload(files, xhrId)

Triggered after the request is sent(xhr send | form submit).

@param files {Filelist | String} The array contains files.

@param xhrId {Number} Id of this uploading xhr. Could be useful for abort.

@return your return

onAbort(xhrId)

Triggered after you aborting a xhr.

@param xhrId {Number} Id of the xhr aborted.

@return your return

uploading(progress)

It will be triggered continuously when the file is uploading in moderns.

@param progress {Progress} Progress instance,useful properties such as loaded and total can be found.

@return your return

uploadSuccess(res)

Callback when upload succeed (according to the ajax simply).

@param res {String} The response is formatted according to options.dataType(json or text).

@return your return

uploadError

Callback when error occurred (according to the ajax simply).

@param err {Object} If this is an error that caught by try, it will be an object with type and message.

@return your return

Custom Buttons

You can display two of your custom buttons by setting two attributes of ReactUploadFile as mentioned before.

chooseFileButton

Component to choose files.

uploadFileButton(optional)

Component that triggers uploading. If not specified, files will be uploaded immediately after chosen.

<ReactUploadFile options={...} chooseFileButton={<YourChooseButton />} uploadFileButton={<YourUploadButton />} />

Will be rendered like this:

<YourChooseButton {...} /><YourUploadButton {...} />

If you don't set the uploadFile attribute, then ReactUploadFile will upload the files immediately after you choose files.

<ReactUploadFile options={...} chooseFileButton={<YourChooseButton />} />

Component Functions

Get component reference via ref. eg:

componentDidMount() {
  this.upload.manuallyChooseFile();
}
 
todo() {
  this.upload.processFile(files => files)
}
 
render() {
  return (
    <ReactUploadFile ref={(upload) => {this.upload = upload;}} options={...} chooseFileButton={<YourChooseButton />} uploadFileButton={<YourUploadButton />} didChoose={this.todo} />
  );
}

processFile(func)

Process files with customed function.

@param func {Function} Receive filelist as param

@return null

manuallyChooseFile()

Do the same as clicking chooseFileButton. Only support modern browsers.

@param null

@return null

manuallyUploadFile(files)

Upload files manually, use this function. BeforeUpload() won't be triggered after the invoke of this function.

@param files {Filelist} filelist that need to be uploaded, default to the filelist of chosen files.

@return null

abort(xhrId)

Abort a xhr. Temporarily only works in modern browsers.

@param xhrId {Number} If not passing an id, will abort the newest one. You can get it in didUpload().

Examples

Simple example:

import ReactUploadFile from 'react-upload-file';
...
render() {
  /* set properties */
  const options = {
    baseUrl: 'http://127.0.0.1',
    query: {
      warrior: 'fight'
    }
  }
  /* Use ReactUploadFile with options */
  /* Custom your buttons */
  return (
    <ReactUploadFile options={options} chooseFileButton={<YourChooseButton />} uploadFileButton={<YourUploadButton />} />
  );
}

Most of the options may be set like:

options: {
  baseUrl: 'http://localhost:8080/upload',
  // query: {
  //   category: '1',
  //   _: Date().getTime()
  // },
  query: (files)=>{
    const l = files.length;
    const queryObj = {};
    for(let i = l-1; i >= 0; --i) {
      queryObj[i] = files[i].name;
    }
    return queryObj;
  }
  // body: {
  //   purpose: 'save'
  // },
  body: (files)=>{
    const l = files.length;
    const queryObj = {};
    for(let i = l-1; i >= 0; --i) {
      queryObj[i] = files[i].name;
    }
    return queryObj;
  },
  dataType: 'json',
  multiple: true,
  numberLimit: 9,
  accept: 'image/*',
  // fileFieldName: 'file',
  fileFieldName: (file) {
    return file.name;
  },
  withCredentials: false,
  requestHeaders: {
    'User-Agent': 'Warrior!'
  },
  beforeChoose: () => {
    return user.isAllowUpload;
  },
  didChoose: (files) => {
    console.log('you choose', typeof files == 'string' ? files : files[0].name);
  },
  beforeUpload: (files) => {
    if (typeof files === 'string') return true;
    if (files[0].size < 1024 * 1024 * 20) {
      files[0].mill = mill;
      return true;
    }
    return false;
  },
  didUpload: (files) => {
    console.log('you just uploaded', typeof files === 'string' ? files : files[0].name);
  },
  uploading: (progress) => {
    console.log('loading...', progress.loaded / progress.total + '%');
  },
  uploadSuccess: (resp) => {
    console.log('upload success!');
  },
  uploadError: (err) => {
    alert(err.message);
  }
}
 
if (typeof window === 'undefined') {
  options.userAgent = this.props.userAgent;
}
 

Author

Warrior! from HCI@SCAU

License

MIT

Package Sidebar

Install

npm i react-upload-file

Weekly Downloads

104

Version

2.0.0-beta.6

License

MIT

Last publish

Collaborators

  • wubocong