JS - 文件上传组件WebUploader使用详解10（常用API方法介绍）

作者：hangge | 2019-02-01 08:10

WebUploader 也提供了许多 API 方法让我们可以对整个上传流程进行控制管理，下面对其一一介绍。

1，getStats 方法（获取文件统计信息）

（1）该方法调用后会返回一个包含以下信息的对象：

successNum：上传成功的文件数
progressNum：上传中的文件数
cancelNum：被删除的文件数
invalidNum：无效的文件数
uploadFailNum：上传失败的文件数
queueNum：还在队列中的文件数
interruptNum：被暂停的文件数

（2）使用样例

var stats = uploader.getStats();
console.log(stats);

2，option 方法（获取或者设置配置项）

（1）获取 Uploader 配置项

// 获取图片压缩配置项
uploader.option( 'compress');

（2）设置 Uploader 配置项

// 修改后图片上传前，尝试将图片压缩到1600 * 1600
uploader.option( 'compress', {
    width: 1600,
    height: 1600
});

3，destroy 方法（销毁 webuploader 实例）

uploader.destroy()

4，addButton 方法（添加文件选择按钮）

如果一个按钮不够，需要调用此方法来添加。参数跟 options.pick 一致。

uploader.addButton({
    id: '#btnContainer',
    innerHTML: '选择文件'
});

5，makeThumb 方法（生成缩略图）

（1）该方法可以指定宽高、也可以不指定宽高。如果不指定宽高的话，则使用初始配置值（默认值为：110 * 110）。

makeThumb( file, callback ) ⇒ undefined
makeThumb( file, callback, width, height ) ⇒ undefined

（2）makeThumb 方法参数说明：

由于生成缩略图过程是异步的，所以需要传入 callback。通常情况在图片加入队里后调用此方法来生成预览图以增强交互效果。
width 和 height 为生成的缩略图宽高。当 width 或者 height 的值介于 0 - 1 时，被当成百分比使用。

（3）callback 中可以接收到两个参数，具体如下：

第一个为 error，如果生成缩略图有错误，此 error 将为真。
第二个为 ret，缩略图的 Data URL 值。

（4）makeThumb 方法具体的使用样例，可以参考我之前写的这篇文章：

JS - 文件上传组件WebUploader使用详解6（图片上传1：带缩略图预览）

6，md5File 方法（计算文件 md5 值）

该方法返回一个 promise 对象，可以监听 progress 进度。

uploader.on( 'fileQueued', function( file ) {
    var $li = ...;

    uploader.md5File( file )

        // 及时显示进度
        .progress(function(percentage) {
            console.log('Percentage:', percentage);
        })

        // 完成
        .then(function(val) {
            console.log('md5 result:', val);
        });

});

7，addFiles 方法（添加文件到队列）

我们可以添加单个文件对象到队列，也可以添加个文件数组到队列。

uploader.addFiles( file ) ⇒ undefined
uploader.addFiles( [file1, file2 ...] ) ⇒ undefined

8，removeFile 方法（从队列移除某一文件）

（1）我们可以传入 File 对象，或者 File 对象的 id 来移除某一文件。

（2）默认情况下移除时只会标记文件状态为已取消，如果第二个参数为 true 则会从 queue 中移除。

$li.on('click', '.remove-this', function() {
    uploader.removeFile( file );
})

9，getFiles 方法（返回指定状态的文件集合）

不传参数将返回所有状态的文件。

// 输出所有的文件
console.log( uploader.getFiles() );

// 输出所有上传失败的文件
console.log( uploader.getFiles('error') );

// 输出所有上传失败、或者被移除的文件
console.log( uploader.getFiles('error', 'cancelled') );

10，retry 方法（重试上传）

可以重试指定文件，或者从出错的文件开始重新上传。

// 从出错的文件开始重新上传
uploader.retry();

// 重试指定文件
uploader.retry(file);

11，sort 方法（排序队列中的文件）

使用该方法可以在上传之前调整上传顺序。

uploader.sort( fn )

12，reset 方法（重置队列）

uploader.reset()

13，predictRuntimeType 方法（预测 Uploader 将采用哪个 Runtime）

uploader.predictRuntimeType()

14，upload 方法（开始上传）

（1）该方法可以从初始状态调用开始上传流程，也可以从暂停状态调用，继续上传流程。

uploader.upload()

（2）该方法可以指定开始某一个文件。我们可以传入 File 对象，或者 File 对象的 id 来开始。

uploader.upload( file | fileId)

15，stop 方法（暂停上传）

（1）该方法不带参数则表示暂停所有上传文件。

uploader.stop()

（2）第一个参数为 true 则中断上传当前正在上传的文件。

uploader.stop(true)

（3）如果第一个参数是文件，则只暂停指定文件。

uploader.stop(file)

16，cancelFile（取消指定文件上传）

（1）该方法会标记文件状态为已取消, 同时中断文件传输。

（2）我们可以传入 File 对象，或者 File 对象的 id 来指定取消的文件。

uploader.cancelFile( file | fileId)

17，isInProgress（判断是否正在上传）

该方法会返回一个 Boolean 值，表示 Uplaoder 当前是否正在上传中。

uploader.isInProgress()

18，skipFile（跳过一个文件上传）

直接跳过指定文件，并将其标记为为已上传状态。

uploader.skipFile( file )

其他