七牛云使用文档

1.x 文档2.x 文档下载示例1.x概述Qiniu-JavaScript-SDK （下文简称为 JS-SDK）适用于 IE8+、Chrome、Firefox、Safari 等浏览器，基于七牛云存储官方 API 构建，其中上传功能基于 Plupload 插件封装。开发者基于 JS-SDK 可以方便的从浏览器端上传文件至七牛云存储，并对上传成功后的图片进行丰富的数据处理操作。不考虑兼容性的情况下，如

SeriousLose

2007人浏览 · 2021-08-31 09:06:29

SeriousLose · 2021-08-31 09:06:29 发布

1.x 文档
 2.x 文档
 下载示例

1.x概述

Qiniu-JavaScript-SDK （下文简称为 JS-SDK）适用于 IE8+、Chrome、Firefox、Safari 等浏览器，基于七牛云存储官方 API 构建，其中上传功能基于 Plupload 插件封装。开发者基于 JS-SDK 可以方便的从浏览器端上传文件至七牛云存储，并对上传成功后的图片进行丰富的数据处理操作。

不考虑兼容性的情况下，如手机端，建议直接使用 Formdata 结合七牛表单上传的方式上传文件。

Qiniu-JavaScript-SDK 为客户端 SDK，没有包含 token 生成实现，为了安全，token 建议通过网络从服务端获取，具体生成代码可以参考以下服务端 SDK 的文档。

2.x概述

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 的文档。

差别

兼容性:

1.x IE8+、Chrome、Firefox、Safari 等浏览器
2.x IE11、Edge、Chrome、Firefox、Safari 等浏览器
2.x 兼容低版本浏览器需要额外的插件如 plupload，JS-SDK babel-polyfill

1.x功能简介

上传
- html5 模式大于 4M 时可分块上传，小于4M时直传
- 分块上传时，可以断点续上传
- flash、html4 模式直接上传
- 继承了 plupload 的功能，可筛选文件上传、拖曳上传等
下载（公开资源）
数据处理（图片）
- imageView2（缩略图）
- imageMogr2（高级处理，包含缩放、裁剪、旋转等）
- imageInfo （获取基本信息）
- exif （获取图片 EXIF 信息）
- watermark （文字、图片水印）
- pipeline （管道，可对 imageView2、imageMogr2、watermark 进行链式处理）

2.x功能简介

上传
- 大于 4M 时可分块上传，小于 4M 时直传
- 分块上传时，支持断点续传
数据处理（图片）
- imageView2（缩略图）
- imageMogr2（高级处理，包含缩放、裁剪、旋转等）
- imageInfo （获取基本信息）
- exif （获取图片 EXIF 信息）
- watermark （文字、图片水印）
- pipeline （管道，可对 imageView2、imageMogr2、watermark 进行链式处理）

差别

1.x支持,2.x不支持
- flash、html4 模式直接上传
- 继承了 plupload 的功能，可筛选文件上传、拖曳上传等

1.x安装

支持以下几种安装方式

直接使用CDN 加速的静态文件地址，访问开放静态文件 CDN ，搜索 qiniu
```
https://cdn.staticfile.org/qiniu-JS-SDK/<version>/qiniu.min.js
```
使用 Bower 安装

Bower 是一个客户端技术的软件包管理器，它可用于搜索、安装和卸载如 JavaScript、HTML、CSS 之类的网络资源。如果需要更详细的关于 Bower 的使用说明，您可以访问 Bower 官方网站。

通过 Bower 安装会将 JS-SDK 依赖的 plupload 也一起安装在 bower_components 中：
```
bower install qiniu
```
执行之后，JS-SDK 和 plupload 分别在以下位置
```
bower_components
├── plupload
│   └── js
│       ├── moxie.js
│       ├── moxie.min.js
│       ├── plupload.dev.js
│       ├── plupload.full.min.js
│       └── plupload.min.js
└── qiniu
    └── dist
        ├── qiniu.js
        ├── qiniu.min.js
        └── qiniu.min.map
```
使用 NPM 安装

NPM 的全称是 Node Package Manager，是一个 NodeJS 包管理和分发工具，已经成为了非官方的发布 Node 模块（包）的标准。如果需要更详细的关于 NPM 的使用说明，您可以访问 NPM 官方网站，或对应的中文网站
```
npm install qiniu-js
```
执行之后，JS-SDK 在以下位置
```
node_modules
└── qiniu-js
    └── dist
        ├── qiniu.js
        ├── qiniu.min.js
        └── qiniu.min.map
```
通过 Github 上的 qiniu/js-sdk 仓库获取

下载最新的发布版本并解压或直接克隆仓库
```
git clone https://github.com/qiniu/js-sdk.git
```
JS-SDK 在 dist 目录中

2.x引入

支持以下几种安装方式

直接使用静态文件地址：
```
https://unpkg.com/qiniu-js@<version>/dist/qiniu.min.js
```
通过sctipt标签引入该文件，会在全局生成名为 qiniu 的对象
使用 NPM 安装

NPM 的全称是 Node Package Manager，是一个 NodeJS 包管理和分发工具，已经成为了非官方的发布 Node 模块（包）的标准。如果需要更详细的关于 NPM 的使用说明，您可以访问 NPM 官方网站，或对应的中文网站
```
npm install qiniu-js
```
```
var qiniu = require('qiniu-js')
// or
import * as qiniu from 'qiniu-js'
```
通过源码编译

git clone git@github.com:qiniu/js-sdk.git，进入项目根目录执行 npm install ，执行 npm run build，即可在dist 目录生成 qiniu.min.js。

使用

上传功能

在页面中引入 plupload，plupload.full.min.js（生产环境）或引入plupload.dev.js和moxie.js（开发调试）
在页面中引入 qiniu.min.js（生产环境）或 qiniu.js（开发调试）

初始化 uploader，请确保在执行初始化时，页面已经引入 plupload

var uploader = Qiniu.uploader({
    disable_statistics_report: false,   // 禁止自动发送上传统计信息到七牛，默认允许发送
    runtimes: 'html5,flash,html4',      // 上传模式,依次退化
    browse_button: 'pickfiles',         // 上传选择的点选按钮，**必需**
    // 在初始化时，uptoken, uptoken_url, uptoken_func 三个参数中必须有一个被设置
    // 切如果提供了多个，其优先级为 uptoken > uptoken_url > uptoken_func
    // 其中 uptoken 是直接提供上传凭证，uptoken_url 是提供了获取上传凭证的地址，如果需要定制获取 uptoken 的过程则可以设置 uptoken_func
    // uptoken : '<Your upload token>', // uptoken 是上传凭证，由其他程序生成
    // uptoken_url: '/uptoken',         // Ajax 请求 uptoken 的 Url，**强烈建议设置**（服务端提供）
    // uptoken_func: function(file){    // 在需要获取 uptoken 时，该方法会被调用
    //    // do something
    //    return uptoken;
    // },
    get_new_uptoken: false,             // 设置上传文件的时候是否每次都重新获取新的 uptoken
    // downtoken_url: '/downtoken',
    // Ajax请求downToken的Url，私有空间时使用,JS-SDK 将向该地址POST文件的key和domain,服务端返回的JSON必须包含`url`字段，`url`值为该文件的下载地址
    // unique_names: true,              // 默认 false，key 为文件名。若开启该选项，JS-SDK 会为每个文件自动生成key（文件名）
    // save_key: true,                  // 默认 false。若在服务端生成 uptoken 的上传策略中指定了 `save_key`，则开启，SDK在前端将不对key进行任何处理
    domain: '<Your bucket domain>',     // bucket 域名，下载资源时用到，如：'http://xxx.bkt.clouddn.com/' **必需**
    container: 'container',             // 上传区域 DOM ID，默认是 browser_button 的父元素，
    max_file_size: '100mb',             // 最大文件体积限制
    flash_swf_url: 'path/of/plupload/Moxie.swf',  //引入 flash,相对路径
    max_retries: 3,                     // 上传失败最大重试次数
    dragdrop: true,                     // 开启可拖曳上传
    drop_element: 'container',          // 拖曳上传区域元素的 ID，拖曳文件或文件夹后可触发上传
    chunk_size: '4mb',                  // 分块上传时，每块的体积
    auto_start: true,                   // 选择文件后自动上传，若关闭需要自己绑定事件触发上传,
    //x_vars : {
    //    自定义变量，参考http://developer.qiniu.com/docs/v6/api/overview/up/response/vars.html
    //    'time' : function(up,file) {
    //        var time = (new Date()).getTime();
              // do something with 'time'
    //        return time;
    //    },
    //    'size' : function(up,file) {
    //        var size = file.size;
              // do something with 'size'
    //        return size;
    //    }
    //},
    init: {
        'FilesAdded': function(up, files) {
            plupload.each(files, function(file) {
              // 文件添加进队列后,处理相关的事情
            });
        },
        'BeforeUpload': function(up, file) {
            // 每个文件上传前,处理相关的事情
        },
        'UploadProgress': function(up, file) {
            // 每个文件上传时,处理相关的事情
        },
        'FileUploaded': function(up, file, info) {
            // 每个文件上传成功后,处理相关的事情
            // 其中 info.response 是文件上传成功后，服务端返回的json，形式如
            // {
            //    "hash": "Fh8xVqod2MQ1mocfI4S4KpRL6D98",
            //    "key": "gogopher.jpg"
            //  }
            // 参考http://developer.qiniu.com/docs/v6/api/overview/up/response/simple-response.html
        // var domain = up.getOption('domain');
            // var res = parseJSON(info.response);
            // var sourceLink = domain + res.key; 获取上传成功后的文件的Url
        },
        'Error': function(up, err, errTip) {
            //上传出错时,处理相关的事情
        },
        'UploadComplete': function() {
            //队列文件处理完毕后,处理相关的事情
        },
        'Key': function(up, file) {
            // 若想在前端对每个文件的key进行个性化处理，可以配置该函数
            // 该配置必须要在 unique_names: false , save_key: false 时才生效
            var key = "";
        // do something with key here
            return key
        }
    }
});

// domain 为七牛空间（bucket)对应的域名，选择某个空间后，可通过"空间设置->基本设置->域名设置"查看获取
// uploader 为一个 plupload 对象，继承了所有 plupload 的方法，参考http://plupload.com/docs

 up.start(); // 开始上传
 up.stop(); // 暂停上传
 up.addFile(file,[fileName]) // 向上传队列中添加文件，如果成功添加了文件，会触发FilesAdded事件。参数file为要添加的文件，可以是一个原生的文件，或者一个plupload文件对象，或者一个iput[type="file"]元素，还可以是一个包括前面那几种东西的数组；fileName为给该文件指定的名称
 up.removeFile(file); // 删除文件 从上传队列中移除文件，参数file为plupload文件对象或先前指定的文件名称,id也可以
 up.splice(start,length); // 从上传队列中移除一部分文件，start为开始移除文件在队列中的素引，1ength为要移除的文件的数量，该方法的返回值为被移除的文件。该方法会触发FilesRemoved 和QueueChange事件

使用

qiniu.upload 返回一个 observable 对象用来控制上传行为，observable 对像通过 subscribe 方法可以被 observer 所订阅，订阅同时会开始触发上传，同时返回一个 subscription 对象，该对象有一个 unsubscribe 方法取消订阅，同时终止上传行为。对于不支持 sdk 的浏览器可以参考 demo1 中用插件处理和 form 直传的方式；一般 form 提交常常会导致网页跳转，demo1 中 form 直传通过加入 iframe，并结合后端 sdk 上传来解决网页跳转问题，实现 form 无刷新上传。分片上传时，JS-SDK支持断点续传功能，会把已上传片的后端返回值ctx信息存储到本地，有效期为一天，超过一天后，当继续上传该文件时会清除掉本地存储信息重新上传。

Example

文件上传：

var observable = qiniu.upload(file, key, token, putExtra, config)

var subscription = observable.subscribe(observer) // 上传开始
// or
var subscription = observable.subscribe(next, error, complete) // 这样传参形式也可以

subscription.unsubscribe() // 上传取消

图片上传前压缩：

let options = {
  quality: 0.92,
  noCompressIfLarger: true
  // maxWidth: 1000,
  // maxHeight: 618
}
qiniu.compressImage(file, options).then(data => {
  var observable = qiniu.upload(data.dist, key, token, putExtra, config)
  var subscription = observable.subscribe(observer) // 上传开始
})

qiniu.upload(file: blob, key: string, token: string, putExtra: object, config: object): observable

observable: 为一个带有 subscribe 方法的类实例
- observable.subscribe(observer: object): subscription
  - observer: observer 为一个 object，用来设置上传过程的监听函数，有三个属性 next、error、complete:
```
var observer = {
  next(res){
    // ...
  },
  error(err){
    // ...
  },
  complete(res){
    // ...
  }
}
```
    - next: 接收上传进度信息，res是一个带有 total 字段的 object，包含loaded、total、percent三个属性，提供上传进度信息。
      - total.loaded: number，已上传大小，单位为字节。
      - total.total: number，本次上传的总量控制信息，单位为字节，注意这里的 total 跟文件大小并不一致。
      - total.percent: number，当前上传进度，范围：0～100。
    - error: 上传错误后触发；自动重试本身并不会触发该错误，而当重试次数到达上限后则可以触发。当不是 xhr 请求错误时，会把当前错误产生原因直接抛出，诸如 JSON 解析异常等；当产生 xhr 请求错误时，参数 err 为一个包含 code、message、isRequestError 三个属性的 object：
      - err.isRequestError: 用于区分是否 xhr 请求错误；当 xhr 请求出现错误并且后端通过 HTTP 状态码返回了错误信息时，该参数为 true；否则为 undefined 。
      - err.reqId: string，xhr请求错误的 X-Reqid。
      - err.code: number，请求错误状态码，只有在 err.isRequestError 为 true 的时候才有效。可查阅码值对应说明。
      - err.message: string，错误信息，包含错误码，当后端返回提示信息时也会有相应的错误信息。
    - complete: 接收上传完成后的后端返回信息，具体返回结构取决于后端sdk的配置，可参考上传策略。
  - subscription: 为一个带有 unsubscribe 方法的类实例，通过调用 subscription.unsubscribe() 停止当前文件上传。
file: Blob 对象，上传的文件
key: 文件资源名
token: 上传验证信息，前端通过接口请求后端获得
config: object
```
var config = {
  useCdnDomain: true,
  region: qiniu.region.z2
};
```
- config.useCdnDomain: 表示是否使用 cdn 加速域名，为布尔值，true 表示使用，默认为 false。
- config.disableStatisticsReport: 是否禁用日志报告，为布尔值，默认为 false。
- config.uphost: 上传 host，类型为 string，如果设定该参数则优先使用该参数作为上传地址，默认为 null。
- config.region: 选择上传域名区域；当为 null 或 undefined 时，自动分析上传域名区域。
- config.retryCount: 上传自动重试次数（整体重试次数，而不是某个分片的重试次数）；默认 3 次（即上传失败后最多重试两次）；目前仅在上传过程中产生 599 内部错误时生效，但是未来很可能会扩展为支持更多的情况。
- config.concurrentRequestLimit: 分片上传的并发请求量，number，默认为3；因为浏览器本身也会限制最大并发量，所以最大并发量与浏览器有关。
- config.checkByMD5: 是否开启 MD5 校验，为布尔值；在断点续传时，开启 MD5 校验会将已上传的分片与当前分片进行 MD5 值比对，若不一致，则重传该分片，避免使用错误的分片。读取分片内容并计算 MD5 需要花费一定的时间，因此会稍微增加断点续传时的耗时，默认为 false，不开启。
- config.forceDirect: 是否上传全部采用直传方式，为布尔值；为 true 时则上传方式全部为直传 form 方式，禁用断点续传，默认 false。

putExtra:

var putExtra = {
  fname: "",
  params: {},
  mimeType: [] || null
};

fname: string，文件原文件名
params: object，用来放置自定义变量
mimeType: null || array，用来限制上传文件类型，为 null 时表示不对文件类型限制；限制类型放到数组里：
["image/png", "image/jpeg", "image/gif"]

// 七牛云配置
{
  "AccessKey": "ij8I8BxX45VCRzHDo3d71_JIjOy5j0TZf5oBTijO", 
  "SecretKey": "6f14PAqU7KqITdOv3-kWegcZMsscoW6QVqgnc2a6",
  "Bucket": "long",
  "Port": 9000,
  "UptokenUrl": "uptoken",
  "Domain": "http://pvhy1v6ou.bkt.clouddn.com/"
}