# uploader

Uploader模块管理网络上传任务，用于从本地上传各种文件到服务器，并支持跨域访问操作。通过plus.uploader可获取上传管理对象。Uploader上传使用HTTP的POST方式提交数据，数据格式符合Multipart/form-data规范，即rfc1867（Form-based File Upload in HTML）协议。

## 方法：

- createUpload: 新建上传任务
- clear: 清除上传任务
- enumerate: 枚举上传任务
- startAll: 开始所有上传任务

## 对象：

- Upload: Upload对象管理一个上传任务
- UploadEvent: 上传任务事件类型
- UploadState: 上传任务的状态，Number类型
- UploadOptions: JSON对象，创建上传任务的参数
- UploadFileOptions: JSON对象，添加上传文件的参数

## 回调方法：

- UploadCompletedCallback: 上传任务完成时的回调函数
- UploadStateChangedCallback: 上传任务状态变化回调函数，在上传任务状态发生变化时调用
- UploadEnumerateCallback: 枚举上传任务回调函数，在枚举上传任务完成时时调用

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"Uploader": {
    		"description": "文件上传，管理文件上传任务"
    	}
    }
    }

# Upload

Upload对象管理一个上传任务

    interface Upload {
    	readonly attribute String url;
    	readonly attribute Number state;
    	readonly attribute UploadOptions options;
    	readonly attribute String responseText;
    	readonly attribute Number uploadedSize;
    	readonly attribute Number totalSize;
    	function void abort();
    	function Boolean addData( String key, String value );
    	function void addEventListener( String event, function Callback listener, Boolean capture );
    	function Boolean addFile( String path, UploadFileOptions options );
    	function String getAllResponseHeaders();
    	function String getResponseHeader( headerName );
    	function void pause();
    	function void resume();
    	function void setRequestHeader( String headerName, String headerValue );
    	function void start();
    }

## 属性：

- id: 上传任务的标识
- url: 上传文件的服务器地址
- state: 任务的状态
- options: 上传任务的参数
- responseText: 上传任务完成后服务器返回的数据
- uploadedSize: 已完成上传数据的大小）
- totalSize: 上传数据的总大小

## 方法：

- addFile: 添加上传文件
- addData: 添加上传数据
- start: 开始上传任务
- pause: 暂停上传任务
- resume: 恢复暂停的上传任务
- abort: 取消上传任务
- addEventListener: 添加上传任务事件监听器
- getAllResponseHeaders: 获取上传请求HTTP响应头部信息
- getResponseHeader: 获取上传请求指定的HTTP响应头部的值
- setRequestHeader: 设置上传请求的HTTP头数据

# UploadEvent

上传任务事件类型

## 常量：

- "statechanged": (String 类型 )上传任务状态变化事件

  当上传任务状态发生变化时触发此事件，事件原型参考UploadStateChangedCallback。

# UploadState

上传任务的状态，Number类型

## 常量：

- undefined: (undefined 类型 )上传任务未开始

  通过plus.uploader.createUpload()方法创建上传任务后的初始状态，此时可调用其start()方法开始上传。

- 0: (number 类型 )上传任务开始调度

  调用上传任务的start()方法之后处于此状态，此时上传任务处于可调度上传状态。

- 1: (number 类型 )上传任务开始请求

  上传任务建立网络连接，发送请求到服务器并等待服务器的响应。

- 2: (number 类型 )上传任务请求已经建立

  上传任务网络连接已建立，服务器返回响应，准备传输数据内容。

- 3: (number 类型 )上传任务提交数据

  上传任务提交数据，监听statechanged事件时可多次触发此状态。

- 4: (number 类型 )上传任务已完成

  上传任务完成数据提交并断开连接，上传成功或失败都会设置为此状态。

- 5: (number 类型 )上传任务已暂停

  调用上传任务的pause()方法将任务暂停，此时可调用其resume()方法重新开始上传。

- -1: (number 类型 )枚举任务状态

  非上传任务状态，泛指所有上传任务的状态，用于enumerate()和clear()操作时指定作用于所有上传任务。

# UploadOptions

JSON对象，创建上传任务的参数

## 属性：

- blocksize: (Number 类型 )上传任务每次上传的文件块大小（仅在支持断点续传的服务有效）

  数值类型，单位为Byte（字节），默认值为102400，若设置值小于等于0则表示不分块上传。

- chunkSize: (Number 类型 )分块上传的大小

  单位为Kb，设置值小于等于0则不分块上传，默认为不分块上传。 Android平台需设置分块上传才能准确触发statechanged返回上传进度，如果不设置分块上传则在开始后快速返回上传完成进度，而实际并没有上传完。 注意：分块上传需要服务器支持，如果服务器不支持则会删除失败。

- method: (String 类型 )网络请求类型

  仅支持http协议的“POST”请求。

- priority: (Number 类型 )上传任务的优先级

  数值类型，数值越大优先级越高，默认优先级值为0。

- retry: (Number 类型 )上传任务重试次数

  数值类型，默认为重试3次。

- retryInterval: (Number 类型 )上传任务重试间隔时间

  数值类型，单位为s(秒)，默认值为30s。

- timeout: (Number 类型 )上传任务超时时间

  数值类型，单位为s(秒)，默认值为120s。 超时时间为服务器响应请求的时间（不是上传任务完成的总时间），如果设置为0则表示永远不超时。

# UploadFileOptions

JSON对象，添加上传文件的参数

## 属性：

- key: (String 类型 )文件键名

  上传文件在上传任务中的键名，默认值为为文件名称。 上传任务中如果已经存在相同key的上传文件或数据将导致添加文件失败。

- name: (String 类型 )文件名称

  上传文件的名称，默认值为上传文件路径中的名称。

- mime: (String 类型 )文件类型

  上传文件的类型（如图片文件为“image/jpeg”），默认值自动根据文件后缀名称生成。

# UploadCompletedCallback

上传任务完成时的回调函数

    void uploadCompleted( Upload upload, Number status ) {
    	// File upload completed code.
    }

## 说明：

在上传任务完成时调用，上传任务失败也将触发此回调。

## 参数：

- upload: ( Upload ) 必选 上传任务对象
- status: ( Number ) 必选 上传结果状态码
  HTTP传输协议状态码，如果未获取传输状态则其值则为0，如上传成功其值通常为200。

## 返回值：

void : 无

# UploadStateChangedCallback

上传任务状态变化回调函数，在上传任务状态发生变化时调用

    void onStateChanged( Upload upload, status ) {
    	// Upload state changed code.
    }

## 参数：

- upload: ( Upload ) 必选 上传任务对象
- status: ( Number ) 必选 上传结果状态码
  HTTP传输协议状态码，如果未获取传输状态则其值则为0，如上传成功其值通常为200。

## 返回值：

void : 无

# UploadEnumerateCallback

枚举上传任务回调函数，在枚举上传任务完成时时调用

    void onEnumerated( Upload[] uploads ) {
    	// Upload enumerate completed code.
    }

## 参数：

- uploads: ( Array[ Upload ] ) 必选 枚举到的上传任务对象数组

## 返回值：

void : 无