对象存储

  • JavaScript SDK

    最近更新时间:2018-03-20 18:32:37

    Qiniu-JavaScript-SDK (下文简称为 JS-SDK)适用于 :IE11、Edge、Chrome、Firefox、Safari 等浏览器,基于七牛云存储官方 API 构建,其中上传功能基于 H5 File API。开发者基于 JS-SDK 可以方便的从浏览器端上传文件至七牛云存储,并对上传成功后的图片进行丰富的数据处理操作。 JS-SDK 兼容支持 H5 File API 的浏览器,在低版本浏览器下,需要额外的插件如 plupload,JS-SDK 提供了一些接口可以结合插件来进行上传工作。

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

    功能简介

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

    准备

    • 在使用 JS-SDK 之前,您必须先注册一个七牛帐号,并登录控制台获取一对有效的 AccessKeySecretKey,您可以阅读 快速入门 安全机制 以进一步了解如何正确使用和管理密钥 。

    • JS-SDK 依赖服务端颁发 token,可以通过以下二种方式实现:

      前端通过接口请求以获得 token 信息

    引入

    支持以下几种安装方式

    • 直接使用静态文件地址:

      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

    上传

    使用

    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() // 上传取消
    

    API 参考

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

    • observable: 为一个带有 subscribe 方法的类实例

      • observable.subscribe(observer: object): subscription

        • observer: observer 为一个 object,用来设置上传过程的监听函数,有三个属性 nexterrorcomplete:

          var observer = {
            next(res){
              // ...
            },
            error(err){
              // ...
            }, 
            complete(res){
              // ...
            }
          }
          
          • next: 接收上传进度信息,res 参数是一个带有 total 字段的 object,包含loadedtotalpercent三个属性,提供上传进度信息。

            • total.loaded: number,已上传大小,单位为字节。
            • total.total: number,本次上传的总量控制信息,单位为字节,注意这里的 total 跟文件大小并不一致。
            • total.percent: number,当前上传进度,范围:0~100。
          • error: 上传错误后触发,当不是 xhr 请求错误时,会把当前错误产生原因直接抛出,诸如 JSON 解析异常等;当产生 xhr 请求错误时,参数 err 为一个包含 codemessageisRequestError 三个属性的 object

            • err.isRequestError: 用于区分是否 xhr 请求错误;当 xhr 请求出现错误并且后端通过 HTTP 状态码返回了错误信息时,该参数为 true;否则为 undefined
            • err.reqId: string,xhr请求错误的 X-Reqid
            • err.code: number,请求错误状态码,只有在 err.isRequestError 为 true 的时候才有效,可查阅码值对应说明
            • err.message: string,错误信息,包含错误码,当后端返回提示信息时也会有相应的错误信息。
          • complete: 接收上传完成后的后端返回信息,res 参数为一个 object, 为上传成功后后端返回的信息,具体返回结构取决于后端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.region: 选择上传域名区域;当为 nullundefined 时,自动分析上传域名区域
      • config.retryCount: 上传自动重试次数(整体重试次数,而不是某个分片的重试次数);默认 3 次(即上传失败后最多重试两次);目前仅在上传过程中产生 599 内部错误时生效但是未来很可能会扩展为支持更多的情况
      • config.concurrentRequestLimit: 分片上传的并发请求量,number,默认为3;因为浏览器本身也会限制最大并发量,所以最大并发量与浏览器有关。
      • config.checkByMD5: 是否开启 MD5 校验,为布尔值;在断点续传时,开启 MD5 校验会将已上传的分片与当前分片进行 MD5 值比对,若不一致,则重传该分片,避免使用错误的分片。读取分片内容并计算 MD5 需要花费一定的时间,因此会稍微增加断点续传时的耗时,默认为 false,不开启。
    • putExtra:

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

    qiniu.createMkFileUrl(url: string, size: number, key: string, putExtra: object): string

    返回创建文件的 url;当分片上传时,我们需要把分片返回的 ctx 信息拼接后通过该 url 上传给七牛以创建文件。

    • url: 上传域名,可以通过qiniu.getUploadUrl()获得
    • size: 文件大小
    • key: 文件资源名
    • putExtra: 同上

      var requestUrl = qiniu.createMkFileUrl(
      uploadUrl,
      file.size,
      key,
      putExtra
      );
      

    qiniu.region: object

    • qiniu.region.z0: 代表华东区域
    • qiniu.region.z1: 代表华北区域
    • qiniu.region.z2: 代表华南区域
    • qiniu.region.na0: 代表北美区域
    • qiniu.region.as0: 代表东南亚区域

    qiniu.getUploadUrl(config: object): string

    接收参数为 config 对象,返回根据 config 里所配置信息的上传域名

      var requestUrl = qiniu.getUploadUrl(config)
    

    qiniu.getHeadersForChunkUpload(token: string): object

    返回 object,包含用来获得分片上传设置的头信息,参数为 token 字符串;当分片上传时,请求需要带该函数返回的头信息

    • token: 后端返回的上传验证信息

      var headers = qiniu.getHeadersForChunkUpload(token)
      

    qiniu.getHeadersForMkFile(token: string): object

    返回 object,包含用来获得文件创建的头信息,参数为 token 字符串;当分片上传完需要把 ctx 信息传给七牛用来创建文件时,请求需要带该函数返回的头信息

      var headers = qiniu.getHeadersForMkFile(token)
    

    qiniu.filterParams(params: object): array

    返回[[k, v],...]格式的数组,k 为自定义变量 key 名,v 为自定义变量值,用来提取 putExtra.params 包含的自定义变量

      var customVarList = qiniu.filterParams(putExtra.params)
    
      for (var i = 0; i < customVarList.length; i++) {
        var k = customVarList[i]
        multipart_params_obj[k[0]] = k[1]
      }
    

    qiniu.watermark(options: object, key: string, domain: string): string(水印)

    返回添加水印后的图片地址

    • key : 文件资源名
    • domain: 为七牛空间(bucket)对应的域名,选择某个空间后,可通过"空间设置->基本设置->域名设置"查看获取,前端可以通过接口请求后端得到

      
      var imgLink = qiniu.watermark({
         mode: 1, // 图片水印
         image: 'http://www.b1.qiniudn.com/images/logo-2.png', // 图片水印的Url,mode = 1 时 **必需**
         dissolve: 50, // 透明度,取值范围1-100,非必需,下同
         gravity: 'SouthWest', // 水印位置,为以下参数[NorthWest、North、NorthEast、West、Center、East、SouthWest、South、SouthEast]之一
         dx: 100,  // 横轴边距,单位:像素(px)
         dy: 100 // 纵轴边距,单位:像素(px)
      }, key, domain) // key 为非必需参数,下同
      
      // imgLink 可以赋值给 html 的 img 元素的 src 属性,下同
      
      // 若未指定key,可以通过以下方式获得完整的 imgLink,下同
      // imgLink  =  '<domain>/<key>?' +  imgLink
      // <domain> 为七牛空间(bucket)对应的域名,选择某个空间后,可通过"空间设置->基本设置->域名设置"查看获取
      
      // 或者
      
      var imgLink = qiniu.watermark({
         mode: 2,  // 文字水印
         text: 'hello world !', // 水印文字,mode = 2 时 **必需**
         dissolve: 50,          // 透明度,取值范围1-100,非必需,下同
         gravity: 'SouthWest',  // 水印位置,同上
         fontsize: 500,         // 字体大小,单位: 缇
         font: '黑体',           // 水印文字字体
         dx: 100,               // 横轴边距,单位:像素(px)
         dy: 100,               // 纵轴边距,单位:像素(px)
         fill: '#FFF000'        // 水印文字颜色,RGB格式,可以是颜色名称
      }, key,domain)
      

      options包含的具体水印参数解释见水印(watermark)

    qiniu.imageView2(options: object, key: string, domain: string): string (缩略)

    返回处理后的图片url

      var 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)

    qiniu.imageMogr2(options: object, key: string, domain: string): string (图像高级处理)

    返回处理后的图片url

      var imgLink = qiniu.imageMogr2({
         "auto-orient": true,      // 布尔值,是否根据原图EXIF信息自动旋正,便于后续处理,建议放在首位。
         strip: true,              // 布尔值,是否去除图片中的元信息
         thumbnail: '1000x1000'    // 缩放操作参数
         crop: '!300x400a10a10',   // 裁剪操作参数
         gravity: 'NorthWest',     // 裁剪锚点参数
         quality: 40,              // 图片质量,取值范围1-100
         rotate: 20,               // 旋转角度,取值范围1-360,缺省为不旋转。
         format: 'png',            // 新图的输出格式,取值范围:jpg,gif,png,webp等
         blur: '3x5'               // 高斯模糊参数
       }, key, domain)
    

    options包含的具体高级图像处理参数解释见图像高级处理(imageMogr2)

    qiniu.imageInfo(key: string, domain: string): Promise

      qiniu.imageInfo(key, domain).then(res => {})
    

    具体 imageInfo 解释见图片基本信息(imageInfo)

    qiniu.exif(key: string, domain: string): Promise

      qiniu.exif(key, domain).then(res => {})
    

    具体 exif 解释见图片 EXIF 信息(exif)

    qiniu.pipeline(fopArr: array, key: string, domain: string): string

      var fopArr = [{
          fop: 'watermark', // 指定watermark操作
          mode: 2,          // 此参数同watermark函数的参数,下同。
          text: 'hello world !',
          dissolve: 50,
          gravity: 'SouthWest',
          fontsize: 500,
          font : '黑体',
          dx: 100,
          dy: 100,
          fill: '#FFF000'
      },{
          fop: 'imageView2', // 指定imageView2操作
          mode: 3,           // 此参数同imageView2函数的参数,下同
          w: 100,
          h: 100,
          q: 100,
          format: 'png'
      },{
          fop: 'imageMogr2',  // 指定imageMogr2操作
          "auto-orient": true,  // 此参数同imageMogr2函数的参数,下同。
          strip: true,
          thumbnail: '1000x1000'
          crop: '!300x400a10a10',
          gravity: 'NorthWest',
          quality: 40,
          rotate: 20,
          format: 'png',
          blur:'3x5'
      }]
    
      // fopArr 可以为三种类型'watermark'、'imageMogr2'、'imageView2'中的任意1-3个
      // 例如只对'watermark'、'imageMogr2'进行管道操作,则如下即可
      // var fopArr = [{
      //    fop: 'watermark', // 指定watermark操作
      //    mode: 2, // 此参数同watermark函数的参数,下同。
      //    text: 'hello world !',
      //    dissolve: 50,
      //     gravity: 'SouthWest',
      //     fontsize: 500,
      //     font : '黑体',
      //     dx: 100,
      //     dy: 100,
      //     fill: '#FFF000'
      // },{
      //    fop: 'imageMogr2',  // 指定imageMogr2操作
      //    "auto-orient": true,  // 此参数同imageMogr2函数的参数,下同。
      //    strip: true,
      //    thumbnail: '1000x1000'
      //    crop: '!300x400a10a10',
      //    gravity: 'NorthWest',
      //    quality: 40,
      //    rotate: 20,
      //    format: 'png',
      //    blur:'3x5'
      // }];
    
      var imgLink = qiniu.pipeline(fopArr, key, domain))
    

    fopArr包含的具体管道操作解释见管道操作

    运行示例

    1. 进入 test 目录,按照目录下的 config.json.example 示例,创建 config.json 文件,其中,Access KeySecret Key 按如下方式获取

      module.exports = {
        AccessKey: "<Your Access Key>",
        SecretKey: "<Your Secret Key>",
        Bucket: "<Your Bucket Name>",
        Port: 19110,
        UptokenUrl: "<Your Uptoken_Url>", // demo 启动后会在本地 /uptoken 上提供获取 uptoken 的接口,所以这里可以填 'token'
        Domain: "<Your Bucket Domain>" // Bucket 的外链默认域名,在 Bucket 的内容管理里查看,如:'http://xxx.bkt.clouddn.com/'
      }
      
    2. 进入项目根目录,执行 npm install 安装依赖库,然后打开两个终端,一个执行 npm run serve 跑 server, 一个执行 npm run dev 运行服务 demo1; demo2 为测试es6语法的 demo,进入 demo2 目录,执行 npm install,然后 npm start 运行 demo2,demo1 和 demo2 都共用一个 server。

    说明

    1. 如果您想了解更多七牛的上传策略,建议您仔细阅读 七牛官方文档-上传。另外,七牛的上传策略是在后端服务指定的.

    2. 如果您想了解更多七牛的图片处理,建议您仔细阅读 七牛官方文档-图片处理

    3. JS-SDK 示例生成 token 时,指定的 Bucket Name 为公开空间,所以可以公开访问上传成功后的资源。若您生成 token 时,指定的 Bucket Name 为私有空间,那您还需要在服务端进行额外的处理才能访问您上传的资源。具体参见下载凭证。JS-SDK 数据处理部分功能不适用于私有空间。

    常见问题

    1. 关于上传文件命名问题,可以参考:

    1. 上传的 scope 为 bucket 的形式,上传后文件资源名以设置的 key 为主,如果 keynull 或者 undefined,则文件资源名会以 hash 值作为资源名。
    2. 上传的 scope 为 bucket:key 的形式,上传文件本地的名字需要和 scope 中的 key 是一致的,不然会报错 key doesn‘t match with scope。
    3. 上传的 scope 为 bucket,但是 token 中有设定 saveKey,这种形式下客户端的 key 如果设定为 null 或者 undefined,则会以 saveKey 作为文件资源名,否则仍然是以 key 值作为资源名,并且上传的本地文件名也是需要和这个 savekey 文件名一致的。

    2. 限制上传文件的类型:

    这里又分为两种方法:

    1. 通过在 token 中设定 mimeLimit 字段限定上传文件的类型,该设定是在后端 sdk 设置,请查看相应的 sdk 文档,示例
      "image/\*": 表示只允许上传图片类型;
      "image/jpeg;image/png": 表示只允许上传 jpg 和 png 类型的图片;
      "!application/json;text/plain": 表示禁止上传 json 文本和纯文本。(注意最前面的感叹号)
      
    2. 通过 putExtramimeType 参数直接在前端限定

    相关资源

    如果您有任何关于我们文档或产品的建议和想法,欢迎您通过以下方式与我们互动讨论:

    • 技术论坛 - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
    • 提交工单 - 如果您的问题不适合在论坛讨论或希望及时解决,您也可以提交一个工单,我们的技术支持人员会第一时间回复您
    • 博客 - 这里会持续更新发布市场活动和技术分享文章
    • 微博
    • 常见问题

    贡献代码

    1. Fork

    2. 创建您的特性分支 git checkout -b my-new-feature

    3. 提交您的改动 git commit -am 'Added some feature'

    4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature

    5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

    许可证

    Copyright (c) 2014 qiniu.com

    基于 MIT 协议发布:

    以上内容是否对您有帮助?
  • Close