Qiniu Cloud JavaScript SDK
基于七牛 API 开发的前端 JavaScript SDK
Qiniu-JavaScript-SDK （下文简称为 JS-SDK）适用于 ：IE11、Edge、Chrome、Firefox、Safari 等浏览器，基于七牛云存储官方 API 构建，其中上传功能基于 H5 File API。开发者基于 JS-SDK 可以方便的从浏览器端上传文件至七牛云存储，并对上传成功后的图片进行丰富的数据处理操作。 JS-SDK 兼容支持 H5 File API 的浏览器，在低版本浏览器下，需要额外的插件如 plupload，JS-SDK 提供了一些接口可以结合插件来进行上传工作，注意：(在低版本浏览器需要引入 babel-polyfill 来解决 SDK 里某些语法或者属性浏览器不能识别的问题)。
Qiniu-JavaScript-SDK 为客户端 SDK，没有包含 token 生成实现，为了安全，token 建议通过网络从服务端获取，具体生成代码可以参考以下服务端 SDK 的文档。
Qiniu-JavaScript-SDK 的示例 Demo 中的服务器端部分是基于 Node.js 服务器端 SDK 开发的。
在使用 JS-SDK 之前，您必须先注册一个七牛帐号，并登录控制台获取一对有效的 AccessKey 和 SecretKey，您可以阅读 快速入门 和 安全机制 以进一步了解如何正确使用和管理密钥 。
JS-SDK 依赖服务端颁发 token，可以通过以下二种方式实现：
前端通过接口请求以获得 token 信息
支持以下几种安装方式
直接使用静态文件地址：
https://cdnjs.cloudflare.com/ajax/libs/qiniu-js/<version>/qiniu.min.js
// 当上方资源链接访问不稳定时，可选使用下方资源链接
https://cdn.staticfile.org/qiniu-js/<version>/qiniu.min.js通过 script 标签引入该文件，会在全局生成名为 qiniu 的对象
使用 NPM 安装
NPM 的全称是 Node Package Manager，是一个 NodeJS 包管理和分发工具，已经成为了非官方的发布 Node 模块（包）的标准。如果需要更详细的关于 NPM 的使用说明，您可以访问 NPM 官方网站，或对应的 中文网站
npm install qiniu-jsconst qiniu = require('qiniu-js')
// or
import * as qiniu from 'qiniu-js'通过源码编译
git clone [email protected]:qiniu/js-sdk.git，进入项目根目录执行 npm install ，执行 npm run build，即可在dist 目录生成 qiniu.min.js。
qiniu.upload 返回一个 observable 对象用来控制上传行为，observable 对像通过 subscribe 方法可以被 observer 所订阅，订阅同时会开始触发上传，同时返回一个 subscription 对象，该对象有一个 unsubscribe 方法取消订阅，同时终止上传行为。对于不支持 SDK 的浏览器可以参考 demo1 中用插件处理和 form 直传的方式； 一般 form 提交常常会导致网页跳转，demo1 中 form 直传通过加入 iframe，并结合后端 SDK 上传来解决网页跳转问题，实现 form 无刷新上传。分片上传时，JS-SDK支持断点续传功能，会把已上传片的后端返回值ctx信息存储到本地，有效期为一天，超过一天后，当继续上传该文件时会清除掉本地存储信息重新上传。
文件上传：
const observable = qiniu.upload(file, key, token, putExtra, config)
const subscription = observable.subscribe(observer) // 上传开始
// or
const subscription = observable.subscribe(next, error, complete) // 这样传参形式也可以
subscription.unsubscribe() // 上传取消图片上传前压缩：
const options = {
quality: 0.92,
noCompressIfLarger: true
// maxWidth: 1000,
// maxHeight: 618
}
qiniu.compressImage(file, options).then(data => {
const observable = qiniu.upload(data.dist, key, token, putExtra, config)
const subscription = observable.subscribe(observer) // 上传开始
})observable: 为一个带有 subscribe 方法的类实例
observable.subscribe(observer: object): subscription
observer: observer 为一个 object，用来设置上传过程的监听函数，有三个属性 next、error、complete:
const observer = {
next(res){
// ...
},
error(err){
// ...
},
complete(res){
// ...
}
}next: 接收上传进度信息的回调函数，回调函数参数值为 object，包含字段信息如下：
object，只有分片上传时才返回该字段Array<ProgressCompose> 每个 chunk 的上传信息，只有分片上传有此字段number chunk 的尺寸number 已经发送完毕的尺寸number 进度比例，范围在 0 - 100boolean 是否是来自缓存loaded、total、percent 三个属性:number，已上传大小，单位为字节。number，本次上传的总量控制信息，单位为字节，注意这里的 total 跟文件大小并不一致。number，当前上传进度，范围：0～100。error: 上传错误后触发；自动重试本身并不会触发该错误，而当重试次数到达上限后则可以触发。当不是 xhr 请求错误时，会把当前错误产生原因直接抛出，诸如 JSON 解析异常等；当产生 xhr 请求错误时，参数 err 的类型为 QiniuError, 对于请求错误，err 的类型为 QiniuRequestError(继承自QiniuError)，如果是由于非服务端原因发生错误时（例如断网、跨域等等），错误的类型为 QiniuNetworkError(继承自QiniuRequestError)。
QiniuErrorQiniuErrorName 错误的类型。string 错误的信息。string 调用堆栈信息。QiniuRequestError 继承自 QiniuErrorany 服务端返回的错误信息，如果不是标准的 json 格式，则该字段为 undefined。string xhr 请求错误的 X-Reqid。number 请求错误状态码，可查阅码值对应 说明。true，不推荐使用，即将废弃。QiniuNetworkError 继承自 QiniuRequestErrorreqId，该字段可能为 ''。complete: 接收上传完成后的后端返回信息，具体返回结构取决于后端 SDK 的配置，可参考 上传策略。
subscription: 为一个带有 unsubscribe 方法的类实例，通过调用 subscription.unsubscribe() 停止当前文件上传。
bucket: 上传的目标空间
file: File 对象，上传的文件
key: 文件资源名，为空字符串时则文件资源名也为空，为 null 或者 undefined 时则自动使用文件的 hash 作为文件名
token: 上传验证信息，前端通过接口请求后端获得
config: object，其中的每一项都为可选
const config = {
useCdnDomain: true,
region: qiniu.region.z2
};true 表示使用，默认为 true。false。host，类型为 string[] | string，如果指定一个非空数组或者非空字符串，则仅使用该数据作为上传 host，默认为 []，传入多个 host 时，内部会在重试过程中根据情况自动切换不同的 host。https 或者 http，默认为 https。null 或 undefined 时，自动分析上传域名区域，当指定了 uphost 时，此设置项无效。number，默认为3；因为浏览器本身也会限制最大并发量，所以最大并发量与浏览器有关。code: 406），默认为 true，不开启。MD5 校验，为布尔值；在断点续传时，开启 MD5 校验会将已上传的分片与当前分片进行 MD5 值比对，若不一致，则重传该分片，避免使用错误的分片。读取分片内容并计算 MD5 需要花费一定的时间，因此会稍微增加断点续传时的耗时，默认为 false，不开启。true 时则上传方式全部为直传 form 方式，禁用断点续传，默认 false。number，分片上传时每片的大小，必须为正整数，单位为 MB，且最大不能超过 1024，默认值 4。因为 chunk 数最大 10000，所以如果文件以你所设的 chunkSize 进行分片并且 chunk 数超过 10000，我们会把你所设的 chunkSize 扩大二倍，如果仍不符合则继续扩大，直到符合条件。INFO | WARN | ERROR | OFF，允许程序在控制台输出日志，默认为 OFF，不输出任何日志，本功能仅仅用于本地调试，不建议在线上环境开启。putExtra: object，其中的每一项都为可选
const putExtra = {
fname: "qiniu.txt",
mimeType: "text/plain",
customVars: { 'x:test': 'qiniu', ... },
metadata: { 'x-qn-meta': 'qiniu', ... },
}; 接收参数为 config 对象，返回根据 config 里所配置信息的上传域名
qiniu.getUploadUrl(config, token).then(res => {}) // res 即为上传的 url 返回 object，包含用来获得分片上传设置的头信息，参数为 token 字符串；当分片上传时，请求需要带该函数返回的头信息
token: 后端返回的上传验证信息
const headers = qiniu.getHeadersForChunkUpload(token) 删除指定上传任务中已上传完成的片，key 为目标文件名，uploadInfo 可通过 next 的返回获取，token 由服务端生成
在 v3.3.3 版本之前，该压缩行为会根据图片的 Orientation(设备角度) 信息对图片进行旋转处理，详细的信息可以参考
issue：关于 canvas 绘制图像的方向兼容处理
const imgLink = qiniu.compressImage(file, options).then(res => {
// res : {
// dist: 压缩后输出的 Blob 对象或原始的 File 对象，具体看下面的 options 配置
// width: 压缩后的图片宽度
// height: 压缩后的图片高度
// }
}
})File 对象，支持 image/png、image/jpeg、image/bmp、image/webp 这几种图片类型objectnumber，图片压缩质量，在图片格式为 image/jpeg 或 image/webp 的情况下生效，其他格式不会生效，可以从 0 到 1 的区间内选择图片的质量。默认值 0.92number，压缩图片的最大宽度值number，压缩图片的最大高度值
（注意：当 maxWidth 和 maxHeight 都不设置时，则采用原图尺寸大小）boolean，为 true 时如果发现压缩后图片大小比原来还大，则返回源图片（即输出的 dist 直接返回了输入的 file）；默认 false，即保证图片尺寸符合要求，但不保证压缩后的图片体积一定变小object，包含如下字段：返回添加水印后的图片地址
…options包含的具体水印参数解释见 水印（watermark）
返回处理后的图片url
const imgLink = qiniu.imageView2({
mode: 3, // 缩略模式，共 6 种 [0-5]
w: 100, // 具体含义由缩略模式决定
h: 100, // 具体含义由缩略模式决定
q: 100, // 新图的图像质量，取值范围：1-100
format: 'png' // 新图的输出格式，取值范围：jpg，gif，png，webp 等
}, key, domain)options包含的具体缩略参数解释见 图片基本处理（imageView2）
返回处理后的图片url
const imgLink = qiniu.imageMogr2({
"auto-orient": true, // 布尔值，是否根据原图EXIF信息自动旋正，便于后续处理，建议放在首位。
strip: true, // 布尔值，是否去除图片中的元信息
thumbnail: '1000x1000' // 缩放操作参数
crop: '!300x400a10a10', // 裁剪操作参数
gravity: 'NorthNo open issues yet, or sync has not completed.