uploader

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

方法：

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Uploader": {
  7.         "description": "文件上传，管理文件上传任务"
  8.     }
  9. }
  10. }

createUpload

新建上传任务

  2. Upload plus.uploader.createUpload( url, options, completedCB );
  3.

说明：

请求上传管理创建新的上传任务，创建成功则返回Upload对象，用于管理上传任务。

参数：

  • url: (String)必选 要上传文件的目标地址上传服务器的url地址，仅支持http或https协议。允许创建多个相同url地址的上传任务。
  • options: (UploadOptions)可选 上传任务的参数可通过此参数设置定义上传任务属性，如请求类型、上传优先级等。
  • completedCB: (UploadCompletedCallback)可选 上传任务完成回调函数当上传任务提交完成时触发，成功或失败都会触发。

返回值：

Upload: Upload对象

示例：

  2. // 创建上传任务
  3. function createUpload() {
  4.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do", 
  5.         { method:"POST",blocksize:204800,priority:100 },
  6.         function ( t, status ) {
  7.             // 上传完成
  8.             if ( status == 200 ) { 
  9.                 alert( "Upload success: " + t.url );
  10.             } else {
  11.                 alert( "Upload failed: " + status );
  12.             }
  13.         }
  14.     );
  15.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  16.     task.addData( "string_key", "string_value" );
  17.     //task.addEventListener( "statechanged", onStateChanged, false );
  18.     task.start();
  19. }
  20.

uni-app使用plus注意事项

clear

清除上传任务

  2. plus.uploader.clear( state );
  3.

说明：

清除指定状态的上传任务。

参数：

  • state: (UploadState)可选 清除上传任务的状态如果未指定state值，则清除所有未完成的上传任务。

返回值：

void: 无

enumerate

枚举上传任务

  2. plus.uploader.enumerate( enumCB, state );
  3.

说明：

枚举指定状态的上传任务列表，通过enumCB回调函数返回结果。

参数：

  • enumCB: (UploadEnumerateCallback)必选 枚举上传任务回调函数枚举上传任务完成时触发。
  • state: (UploadState)可选 枚举上传任务的状态如果未指定state值，则枚举所有未完成的上传任务。

返回值：

void: 无

示例：

  2. // 枚举上传任务
  3. function enumerateUpload() {
  4.     plus.uploader.enumerate( function ( tasks ) {
  5.         alert( "Unfinished task count: " + tasks.length );
  6.     } );
  7. }
  8.

uni-app使用plus注意事项

startAll

开始所有上传任务

  2. plus.uploader.startAll();
  3.

说明：

开始所有处于未开始调度或暂停状态的上传任务。若上传任务数超过可并发处理的总数，超出的任务处于调度状态（等待上传），当有任务完成时根据调度状态任务的优先级选择任务开始上传。

参数：

无

返回值：

void: 无

Upload

Upload对象管理一个上传任务

  2. interface Upload {
  3.     readonly attribute String url;
  4.     readonly attribute Number state;
  5.     readonly attribute UploadOptions options;
  6.     readonly attribute String responseText;
  7.     readonly attribute Number uploadedSize;
  8.     readonly attribute Number totalSize;
  9.     function void abort();
  10.     function Boolean addData( String key, String value );
  11.     function void addEventListener( String event, function Callback listener, Boolean capture );
  12.     function Boolean addFile( String path, UploadFileOptions options );
  13.     function String getAllResponseHeaders();
  14.     function String getResponseHeader( headerName );
  15.     function void pause();
  16.     function void resume();
  17.     function void setRequestHeader( String headerName, String headerValue );
  18.     function void start();
  19. }
  20.

属性：

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

方法：

id

上传任务的标识

  2. download.id;
  3.

说明：

String类型 只读属性

在创建任务时系统自动分配，用于标识上传任务的唯一性。

url

上传文件的服务器地址

  2. upload.url;
  3.

说明：

String类型 只读属性

调用plus.uploader.createUpload()方法创建上传任务时设置的值。

state

任务的状态

  2. upload.state;
  3.

说明：

Number类型 只读属性

上传任务的状态，参考UploadState，在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。

options

上传任务的参数

  2. upload.options;
  3.

说明：

UploadOptions类型 只读属性

上传任务配置的参数，参考UploadOptions。

responseText

上传任务完成后服务器返回的数据

  2. upload.responseText;
  3.

说明：

String类型 只读属性

表示当前上传任务的状态，可通过addEventListener()方法监听statechanged事件监听任务状态的变化。

uploadedSize

已完成上传数据的大小）

  2. upload.UploadedSize;
  3.

说明：

Number类型 只读属性

整数类型，单位为字节（byte），上传任务开始传输数据时，每次触发statechanged事件或上传任务完成更新。

totalSize

上传数据的总大小

  2. upload.totalSize;
  3.

说明：

Number类型 只读属性

整数类型，单位为字节（byte），上传任务开始传输数据时更新。

addFile

添加上传文件

  2. Boolean upload.addFile( path, options );
  3.

说明：

向上传任务中添加文件，必须在任务开始上传前调用。以下情况会导致添加上传文件失败：1. options参数中指定的key在任务中已经存在，则添加失败返回false；2. path参数指定的文件路径不合法或文件不存在，则添加失败返回false；3. 上传任务已经开始调度，调用此方法则添加失败返回false。

参数：

  • path: (String)必选 添加上传文件的路径仅支持本地文件路径。
  • options: (UploadFileOptions)必选 要添加上传文件的参数可通过此参数设置上传任务属性，如文件标识、文件名称、文件类型等。

返回值：

Boolean: 添加文件成功返回true，失败则返回false。

示例：

  2. // 创建上传任务
  3. function createUpload() {
  4.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
  5.         // 上传完成
  6.         if ( status == 200 ) {
  7.             alert( "Upload success: " + t.url );
  8.         } else {
  9.             alert( "Upload failed: " + status );
  10.         }
  11.     });
  12.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  13.     task.addData( "string_key", "string_value" );
  14.     //task.addEventListener( "statechanged", onStateChanged, false );
  15.     task.start();
  16. }
  17.

uni-app使用plus注意事项

addData

添加上传数据

  2. Boolean upload.addData( key, value );
  3.

说明：

向上传任务中添加数据，必须在任务开始上传前调用。以下情况会导致添加上传文件失败：1. key参数中指定的键名在任务中已经存在，则添加失败返回false；2. 上传任务已经开始调度，调用此方法则添加失败返回false。

参数：

  • key: (String)必选 添加上传数据的键名
  • value: (String)必选 添加上传数据的键值

返回值：

Boolean: 添加成功返回true，失败则返回false。

示例：

  2. // 创建上传任务
  3. function createUpload() {
  4.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
  5.         // 上传完成
  6.         if ( status == 200 ) {
  7.             alert( "Upload success: " + t.url );
  8.         } else {
  9.             alert( "Upload failed: " + status );
  10.         }
  11.     });
  12.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  13.     task.addData( "string_key", "string_value" );
  14.     //task.addEventListener( "statechanged", onStateChanged, false );
  15.     task.start();
  16. }
  17.

uni-app使用plus注意事项

start

开始上传任务

  2. void upload.start();
  3.

说明：

开始调度上传任务，如果任务已经处于开始状态则无任何响应。在创建任务或任务上传失败后调用可重新开始上传。

参数：

无

返回值：

void: 无

示例：

  2. // 创建上传任务
  3. function createUpload() {
  4.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
  5.     // 上传完成
  6.     if ( status == 200 ) {
  7.         alert( "Upload success: " + t.url );
  8.     } else {
  9.         alert( "Upload failed: " + status );
  10.     }
  11.     });
  12.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  13.     task.addData( "string_key", "string_value" );
  14.     //task.addEventListener( "statechanged", onStateChanged, false );
  15.     task.start();
  16. }
  17.

uni-app使用plus注意事项

pause

暂停上传任务

  2. void upload.pause();
  3.

说明：

暂停上传任务，如果任务已经处于初始状态或暂停状态则无任何响应。

参数：

无

返回值：

void: 无

示例：

  2. var task=null;
  3. // 创建上传任务
  4. function createUpload() {
  5.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
  6.         // 上传完成
  7.         if ( status == 200 ) {
  8.             alert( "Upload success: " + t.url );
  9.         } else {
  10.             alert( "Upload failed: " + status );
  11.         }
  12.     });
  13.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  14.     task.addData( "string_key", "string_value" );
  15.     //task.addEventListener( "statechanged", onStateChanged, false );
  16.     task.start();
  17. }
  18. // 暂停上传任务
  19. function pauseUpload() {
  20.     task.pause();
  21. }
  22.

uni-app使用plus注意事项

resume

恢复暂停的上传任务

  2. void upload.resume();
  3.

说明：

继续暂停的上传任务，如果任务处于非暂停状态则无任何响应。

参数：

无

返回值：

void: 无

示例：

  2. var task = null;
  3. // 创建上传任务
  4. function createUpload() {
  5.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
  6.         // 上传完成
  7.         if ( status == 200 ) {
  8.             alert( "Upload success: " + t.url );
  9.         } else {
  10.             alert( "Upload failed: " + status );
  11.         }
  12.     });
  13.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  14.     task.addData( "string_key", "string_value" );
  15.     //task.addEventListener( "statechanged", onStateChanged, false );
  16.     task.start();
  17. }
  18. // 暂停上传任务
  19. function pauseUpload() {
  20.     task.pause();
  21. }
  22. // 恢复上传任务
  23. function resumeUpload() {
  24.     task.resume();
  25. }
  26.

uni-app使用plus注意事项

abort

取消上传任务

  2. void upload.abort();
  3.

说明：

如果任务未完成，则终止上传，并从任务列表中删除。

参数：

无

返回值：

void: 无

示例：

  2. var task = null;
  3. // 创建上传任务
  4. function createUpload() {
  5.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
  6.         // 上传完成
  7.         if ( status == 200 ) {
  8.             alert( "Upload success: " + t.url );
  9.         } else {
  10.             alert( "Upload failed: " + status );
  11.         }
  12.     });
  13.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  14.     task.addData( "string_key", "string_value" );
  15.     //task.addEventListener( "statechanged", onStateChanged, false );
  16.     task.start();
  17. }
  18. // 暂停上传任务
  19. function pauseUpload() {
  20.     task.pause();
  21. }
  22. // 取消上传任务
  23. function abortUpload() {
  24.     task.pause();
  25. }
  26.

uni-app使用plus注意事项

addEventListener

添加上传任务事件监听器

  2. void upload.addEventListener( type, listener, capture );
  3.

说明：

上传任务添加事件监听器后，当监听的事件发生时触发listener回调。

参数：

  • type: (UploadEvent)必选 事件类型
  • listener: (UploadStateChangedCallback)必选 事件监听器回调函数当监听的事件发生时，触发设置的回调函数。
  • capture: (Boolean)可选 事件流处理顺序，暂不支持

返回值：

void: 无

示例：

  2. var task = null;
  3. // 监听上传任务状态
  4. function onStateChanged( upload, status ) {
  5.     if ( upload.state == 4 && status == 200 ) {
  6.         // 上传完成
  7.         alert( "Upload success: " + upload.getFileName() );
  8.     }
  9. }
  10. // 创建上传任务
  11. function createUpload() {
  12.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
  13.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  14.     task.addData( "string_key", "string_value" );
  15.     task.addEventListener( "statechanged", onStateChanged, false );
  16.     task.start();
  17. }
  18. // 暂停上传任务
  19. function pauseUpload() {
  20.     task.pause();
  21. }
  22. // 取消上传任务
  23. function abortUpload() {
  24.     task.abort();
  25. }
  26.

uni-app使用plus注意事项

getAllResponseHeaders

获取上传请求HTTP响应头部信息

  2. String upload.getAllResponseHeaders();
  3.

说明：

HTTP响应头部全部内容作为未解析的字符串返回，如果没有接收到这个HTTP响应头数据或者上传请求未完成则为空字符串。

参数：

无

返回值：

String: HTTP响应头数据

示例：

  2. var task = null;
  3. // 监听上传任务状态
  4. function onStateChanged( upload, status ) {
  5.     if ( upload.state == 4 && status == 200 ) {
  6.         // 获取上传请求响应头数据
  7.         console.log(upload.getAllResponseHeaders()); 
  8.         // 上传完成
  9.         alert( "Upload success: " + upload.getFileName() );
  10.     }
  11. }
  12. // 创建上传任务
  13. function createUpload() {
  14.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
  15.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  16.     task.addData( "string_key", "string_value" );
  17.     task.addEventListener( "statechanged", onStateChanged, false );
  18.     task.start();
  19. }
  20.

uni-app使用plus注意事项

getResponseHeader

获取上传请求指定的HTTP响应头部的值

  2. String upload.getResponseHeader( headerName );
  3.

说明：

其参数是要返回的HTTP响应头部的名称，可以使用任何大小写来制定这个头部名字，和响应头部的比较是不区分大小写的。如果没有接收到这个头部或者伤处请求未完成则为空字符串；如果接收到多个有指定名称的头部，这个头部的值被连接起来并返回，使用逗号和空格分隔开各个头部的值。

参数：

  • headerName: _(String)可选 _HTTP响应头数据名称

返回值：

String: HTTP响应头数据值

示例：

  2. var task = null;
  3. // 监听上传任务状态
  4. function onStateChanged( upload, status ) {
  5.     if ( upload.state == 4 && status == 200 ) {
  6.         // 获取上传请求响应头中的Content-Type值
  7.         console.log(dtask.getResponseHeader("Content-Type"));
  8.         // 上传完成
  9.         alert( "Upload success: " + upload.getFileName() );
  10.     }
  11. }
  12. // 创建上传任务
  13. function createUpload() {
  14.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
  15.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  16.     task.addData( "string_key", "string_value" );
  17.     task.addEventListener( "statechanged", onStateChanged, false );
  18.     task.start();
  19. }
  20.

uni-app使用plus注意事项

setRequestHeader

设置上传请求的HTTP头数据

  2. void upload.setRequestHeader( headerName, headerValue );
  3.

说明：

Http的Header应该包含在通过后续start()调用而发起的请求中，此方法必需在调用start()之前设置才能生效。如果带有指定名称的头部已经被指定了，这个头部的新值就是：之前指定的值，加上逗号、以及这个调用指定的值（形成一个数组）。

参数：

  • headerName: _(String)必选 _HTTP请求的头数据名称
  • headerValue: _(String)必选 _HTTP请求的头数据值

返回值：

void: 无

平台支持：

  • Android- 2.2+(支持): 不支持设置“Content-Type”、“User-Agent”、“Cookie”的值。
  • iOS- 5.1+(支持): 不支持设置“Content-Type”、“User-Agent”的值。

示例：

  2. var task = null;
  3. // 监听上传任务状态
  4. function onStateChanged( upload, status ) {
  5.     if ( upload.state == 4 && status == 200 ) {
  6.         // 获取上传请求响应头中的Content-Type值
  7.         console.log(dtask.getResponseHeader("Content-Type"));
  8.         // 上传完成
  9.         alert( "Upload success: " + upload.getFileName() );
  10.     }
  11. }
  12. // 创建上传任务
  13. function createUpload() {
  14.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
  15.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  16.     task.addData( "string_key", "string_value" );
  17.     // 设置自定义数据头
  18.     task.setRequestHeader('Customer','CustomerValue/XXXXXXXXXXXX');
  19.     task.addEventListener( "statechanged", onStateChanged, false );
  20.     task.start();
  21. }
  22.

uni-app使用plus注意事项

UploadEvent

上传任务事件类型

常量：

  • "statechanged": (String类型)上传任务状态变化事件当上传任务状态发生变化时触发此事件，事件原型参考UploadStateChangedCallback。

示例：

  2. var task = null;
  3. // 监听上传任务状态
  4. function onStateChanged( upload, status ) {
  5.     if ( upload.state == 4 && status == 200 ) {
  6.         // 上传完成
  7.         alert( "Upload success: " + upload.getFileName() );
  8.     }
  9. }
  10. // 创建上传任务
  11. function createUpload() {
  12.     var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
  13.     task.addFile( "_www/a.doc", {key:"testdoc"} );
  14.     task.addData( "string_key", "string_value" );
  15.     task.addEventListener( "statechanged", onStateChanged, false );
  16.     task.start();
  17. }
  18. // 暂停上传任务
  19. function pauseUpload() {
  20.     task.pause();
  21. }
  22. // 取消上传任务
  23. function abortUpload() {
  24.     task.abort();
  25. }
  26.

uni-app使用plus注意事项

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返回上传进度，如果不设置分块上传则在开始后快速返回上传完成进度，而实际并没有上传完。注意：分块上传需要服务器支持，如果服务器不支持则会删除失败。

平台支持

  • Android - ALL (支持)
  • iOS - ALL (不支持): 忽略此属性
    • 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

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

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

说明：

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

参数：

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

返回值：

void: 无

UploadStateChangedCallback

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

  2. void onStateChanged( Upload upload, status ) {
  3.     // Upload state changed code.
  4. }
  5.

参数：

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

返回值：

void: 无

UploadEnumerateCallback

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

  2. void onEnumerated( Upload[] uploads ) {
  3.     // Upload enumerate completed code.
  4. }
  5.

参数：

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

返回值：

void: 无