集成 Web 上传 SDK

JS 版上传 SDK 支持图片的上传，默认支持文件的批量上传、分片上传、并发上传和上传网关域名配置。以下将为您介绍 SDK 的集成、配置等具体操作内容。

SDK 集成

引入 SDK

支持以下两种引入 SDK 方式，您可根据实际需要任选其一。

npm install tt-uploader
   

国内: <script src="https://unpkg.byted-static.com/tt-uploader/${version}/dist/index.js"></script>
			或者
		 <script src="https://unpkg.com/tt-uploader/${version}/dist/index.js"></script>
		 
海外: <script src="https://sf16-unpkg-va.ibytedtos.com/tt-uploader/${version}/dist/index.js"></script>

<!--例如：https://unpkg.com/tt-uploader@1.1.0/dist/index.js-->

	

初始化上传配置

import TTUploader from 'tt-uploader';
const ttUploader = new TTUploader({
    appId: xxx,      // 必填，应用 ID。在应用服务中创建的 AppID，质量监控等以该参数来区分业务方，务必正确填写
    userId: 'xxx',  // 必填，用户 ID。建议设置能识别用户的唯一标识 id，用于上传出错时排查问题，不要传入非 ASCII编码
    // 必填，图片上传相关配置
    imageConfig: {
        serviceId: 'xx'，// 必填，服务 ID。请在 veImageX 控制台-服务管理查看并记录该值。
    }
});

添加上传文件

调用 addImageFile 方法，实现添加上传文件的代码示例如下所示：

const fileKey = ttUploader.addImageFile({
    // 必填，待上传的Blob/File文件
    file: Blob,
    // 必填，从服务端拿到的token，token为一个对象类型，详见下方 stsToken 签名生成 sdk 说明
    stsToken: {
         AccessKeyId: "",
         SecretAccessKey: "",
         SessionToken: "",
         ExpiredTime: "",
         CurrentTime:"",
    }
});

stsToken 签名生成 sdk

上传前需要从服务端获取上传 sts2 签名，签名算法服务端接入，接入方法请参考以下服务端各生成上传凭证文档：

• 生成上传凭证-Golang
• 生成上传凭证-PHP
• 生成上传凭证-Python
• 生成上传凭证-Java
• 生成上传凭证-Nodejs

设置监听事件

设置监听事件，具体代码示例如下所示：

ttUploader.on("complete", (infor) => {
    console.log("complete");
    console.log(infor.uploadResult);
});

ttUploader.on("error", (infor) => {
    console.log(infor.extra);
});

ttUploader.on("progress", (infor) => {
    console.log(infor.percent)
});

详情请参考生命周期。

开始上传

调用 start 方法，传入添加上传文件返回的key值，具体代码示例如下所示：

ttUploader.start(Key);

初始化配置

通用配置

配置属性可在实例化时传入，具体代码示例如下所示：

const ttUploader = new TTUploader({
    userId: "xxx",
    appId: 666,
    imageConfig: {
        serviceId: "xxx"
    }
});

各个配置及其对应作用如下表所示：

图片专用配置

示例如下所示：

imageConfig: {
    serviceId: "xxx"  //服务 ID。请在 veImageX 控制台-服务管理查看并记录该值。
}

代码示例如下所示：

import TTUploader from 'tt-uploader';
import ImagexEncrypt from 'tt-uploader/dist/plugins/imagex-encrypt';
const ttUploader = new TTUploader({
    appId: xxx,      // 必填，应用 ID。在应用服务中创建的 AppID，质量监控等以该参数来区分业务方，务必正确填写
    userId: 'xxx',  // 必填，用户 ID。建议设置能识别用户的唯一标识 id，用于上传出错时排查问题，不要传入非 ASCII编码
    // 必填，图片上传相关配置
    imageConfig: {
        serviceId: 'xx'，// 必填，服务 ID。请在 veImageX 控制台-服务管理查看并记录该值。
        imagexEnableEncrypt: true,
        imagexEncryptKey: 'KwvdQPHlu9MZk9eIZ4ZJAFoJM9ek4xaf',    // 可选
        // 加密场景下要获取图片Meta信息则必填
        imagexPublicKey: `-----BEGIN PUBLIC KEY-----
                          xxxxxxxxxxxxxxxxxxxxxxxx
                          xxxxxxxxxxxxxxxxxxxxxxxxx
                          -----END PUBLIC KEY-----`
    }
});
// 使用加密插件
ttUploader.use(new ImagexEncrypt());

方法

组件的方法及相关示例如下所示：

addImageFile(imageFileOption)

添加上传图片文件，支持返回当前文件的 key 值（上传和取消上传等使用该值）。传入的 imageFileOption 配置如下表所示：

const key = ttUploader.addImageFile({
    file: Blob, // 上传文件的Blob对象
    stsToken: {
         AccessKeyId: "",
         SecretAccessKey: "",
         SessionToken: "",
         ExpiredTime: "",
         CurrentTime:"",
    }，
});
console.log(key);  // 返回的文件 key 值，例如：file_1495442273603_999031

setServiceId(serviceId)

修改初始化配置 imageConfig 中的 serviceId，代码示例如下所示：

ttUploader.setServiceId('xxxxxxx');

start(key)

启动图片上传任务。如果上传被暂停，则再次调用此方法时将从断点处开始上传。你需要传入文件的 key 值，若不传参数，则将开始所有文件的上传。

ttUploader.start();

removeFile(key)

移除某个待上传的文件（取消该文件的上传）。

ttUploader.removeFile("file_1495442273603_999031");

cancel(key)

取消某一正在上传的文件，同时删除暂存的上传信息。传入文件的 key 值，如果不传参数，则将取消所有文件的上传。

ttUploader.cancel();

pause(key)

暂停上传，将暂存当前文件的上传信息。传入文件的 key 值，如果不传参数，则将暂停所有文件的上传。

ttUploader.pause();

restart(key)

恢复上传。传入文件的 key 值，如果不传参数，则将恢复所有文件的上传。

ttUploader.restart();

生命周期

此处的生命周期是指上传某一个文件时候的生命周期，即一个上传过程的各个任务。

捕获某个生命周期，代码示例如下所示：

ttUploader.on("xxx", function(data) {
    console.log("xxx", data);
});

生命周期各阶段如下表所示：

Returned Value

在捕获每一个生命周期时都可获得描述当前状态的 data 信息，该信息在整个周期中不断完善，最终得到的 data 信息如下表所示：

uploadResult

图片上传

错误码