Qiniu-wxapp-SDK

基于七牛云 API 开发的微信小程序 SDK

快速导航

• 准备工作
• 安装与使用
• API
• 说明
• 常见问题
• ChangeLog

最近一次修改：

• 增加了文件在线查看功能，支持的文件格式：支持的文件格式：pdf, doc, docx, xls, xlsx, ppt, pptx。

• 增加了文件上传（从客户端会话）功能，支持从客户端会话中选择图片、视频、其它文件（PDF(.pdf), Word(.doc/.docx), Excel(.xls/.xlsx), PowerPoint(.ppt/.pptx)等文件格式）进行上传。
• demo 页面美化，增加了文件上传（从客户端会话）的UI。
• 增加了对 "通过fileURL下载文件时，自定义下载名" 的说明与样例。
• 增加了demo中获取原文件名的功能演示。
• 补充了更详细的注释，并同步对README.md进行了更新。
• 本次sdk升级兼容上一版本。js 版本更新并兼容。ts 版本已兼容，但未更新优化，ts 版本的更新优化将在日后进行。

概述

Qiniu-wxapp-SDK 是七牛云在小程序上的实现，网络功能依赖于微信小程序 API。您可以基于 SDK 方便的在小程序中上传文件至七牛云。

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

• Java
• PHP
• Python
• Ruby
• Go
• Node.js
• C#
• C/C++

功能简介

• 上传文件，支持图片文件、视频文件、PDF(.pdf), Word(.doc/.docx), Excel(.xls/.xlsx), PowerPoint(.ppt/.pptx)等文件格式。
• 文件在线查看，支持的文件格式：支持的文件格式：pdf, doc, docx, xls, xlsx, ppt, pptx。

其他功能在开发中，敬请期待。

准备

•   从 github 上下载qiniuUploader.js，导入小程序工程。

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

•   SDK 依赖服务端颁发 uptoken，可以通过以下二种方式实现：

  •   利用七牛服务端 SDK 构建后端服务（建议的方式）
  •   利用七牛底层 API 构建服务，详见七牛上传策略和上传凭证

•   您需要了解您的七牛存储空间设置在那个区域，比如华东，华南等，参见区域设置

后端服务应提供一个 URL 地址，供小程序请求该地址后获得 uptoken。请求成功后，服务端应返回如下格式的 json（至少包含 uptoken 字段）：

{
    "uptoken": "0MLvWPnyya1WtPnXFy9KLyGHyFPNdZceomL..."
}

根据你创建的七牛存储空间，把对应的 https 上传地址添加到小程序的访问白名单中，方法如下：

1. 登录 微信公众平台，前往 设置 - 开发设置，点击 服务器配置 下的「修改」链接。
2. 修改 uploadFile 域名(比如华东 https 上传地址为：https://up.qiniup.com，地址不清楚写什么请参见https地址附录)
3. 如果需要下载文件，则还需要一同设置 downloadFile 域名，为你的 bucket 下载地址
4. 保存即可

字段名	内容
request 域名	https://yourServce.com
uploadFile 域名	https://up.qiniup.com （根据存储区域填写）
downloadFile 域名	https://baldkf.bkt.clouddn.com

七牛云文件上传接口，文件向匹配的接口中传输，存储区域对应 HTTPS 地址，参考官方文档

存储区域	区域代码	HTTPS 地址
华东	ECN	https://up.qiniup.com
华北	NCN	https://up-z1.qiniup.com
华南	SCN	https://up-z2.qiniup.com
北美	NA	https://up-na0.qiniup.com
新加坡	ASG	https://up-as0.qiniup.com

注意!! 目前微信限制每月只能修改三次域名白名单。

安装

暂时支持一种安装方式

• 通过 Github 上的 gpake/qiniu-wxapp-sdk 仓库获取

直接克隆仓库

git clone https://github.com/gpake/qiniu-wxapp-sdk.git

qiniuUploader.js 和 qiniuUploader.ts 文件在本项目中的sdk 目录。

使用

上传功能

建议参照demo 的用法，从demo的 index.wxml 页面 上传UI按钮绑定的事件开始看，注释写的很详细。

1. 在需要使用的页面引用js 文件：

const qiniuUploader = require("../../../utils/qiniuUploader");

2. 在需要使用上传功能的页面，开心地使用：

const qiniuUploader = require("../../utils/qiniuUploader");
// index.js

// 初始化七牛云相关配置
function initQiniu() {
    var options = {
        // bucket所在区域，这里是华北区。ECN, SCN, NCN, NA, ASG，分别对应七牛云的：华东，华南，华北，北美，新加坡 5 个区域
        region: 'NCN',

        // 获取uptoken方法三选一即可，执行优先级为：uptoken > uptokenURL > uptokenFunc。三选一，剩下两个置空。推荐使用uptokenURL，详情请见 README.md
        // 由其他程序生成七牛云uptoken，然后直接写入uptoken
        uptoken: '',
        // 从指定 url 通过 HTTP GET 获取 uptoken，返回的格式必须是 json 且包含 uptoken 字段，例如： {"uptoken": "0MLvWPnyy..."}
        uptokenURL: 'https://[yourserver.com]/api/uptoken',
        // uptokenFunc 这个属性的值可以是一个用来生成uptoken的函数，详情请见 README.md
        uptokenFunc: function () { 
        		// do something
    				return qiniuUploadToken;
        },

        // bucket 外链域名，下载资源时用到。如果设置，会在 success callback 的 res 参数加上可以直接使用的 fileURL 字段。否则需要自己拼接
        domain: 'http://[yourBucketId].bkt.clouddn.com',
        // qiniuShouldUseQiniuFileName 如果是 true，则文件的 key 由 qiniu 服务器分配（全局去重）。如果是 false，则文件的 key 使用微信自动生成的 filename。出于初代sdk用户升级后兼容问题的考虑，默认是 false。
        // 微信自动生成的 filename较长，导致fileURL较长。推荐使用{qiniuShouldUseQiniuFileName: true} + "通过fileURL下载文件时，自定义下载名" 的组合方式。
        // 自定义上传key 需要两个条件：1. 此处shouldUseQiniuFileName值为false。 2. 通过修改qiniuUploader.upload方法传入的options参数，可以进行自定义key。（请不要直接在sdk中修改options参数，修改方法请见demo的index.js）
        // 通过fileURL下载文件时，文件自定义下载名，请参考：七牛云“对象存储 > 产品手册 > 下载资源 > 下载设置 > 自定义资源下载名”（https://developer.qiniu.com/kodo/manual/1659/download-setting）。本sdk在README.md的"常见问题"板块中，有"通过fileURL下载文件时，自定义下载名"使用样例。
        shouldUseQiniuFileName: false
    };
    // 将七牛云相关配置初始化进本sdk
    qiniuUploader.init(options);
}

//获取应用实例
var app = getApp()
Page({
    data: {
        // 图片上传（从相册）返回对象。上传完成后，此属性被赋值
        imageObject: {},
        // 文件上传（从客户端会话）返回对象。上传完成后，此属性被赋值
        messageFileObject: {},
        // 图片上传（从相册）进度对象。开始上传后，此属性被赋值
        imageProgress: {},
        // 文件上传（从客户端会话）进度对象。开始上传后，此属性被赋值
        messageFileProgress: {},
        // 文件在线查看来源fileUrl
        viewFileOnlineFileUrl: '',
        // 文件下载进度对象。用于文件在线查看前的预下载
        downloadFileProgress: {},
        // 此属性在qiniuUploader.upload()中被赋值，用于中断上传
        cancelTask: function () { }
    },
    //事件处理函数
    onLoad: function () {
        console.log('onLoad');
        var that = this;
    },
    // 图片上传（从相册）方法
    didPressChooesImage: function () {
        var that = this;
        didPressChooesImage(that);
    },
    // 文件上传（从客户端会话）方法，支持图片、视频、其余文件 (PDF(.pdf), Word(.doc/.docx), Excel(.xls/.xlsx), PowerPoint(.ppt/.pptx)等文件格式)
    didPressChooesMessageFile: function () {
        var that = this;
        didPressChooesMessageFile(that);
    },
    // 在线查看文件，支持的文件格式：pdf, doc, docx, xls, xlsx, ppt, pptx。关于wx.openDocument方法，详情请参考微信官方文档：https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.openDocument.html
    didPressViewFileOnline: function() {
        var that = this;
        didPressViewFileOnline(that);
    },
    // 中断上传方法
    didCancelTask: function () {
        this.data.cancelTask();
    }
});

// 图片上传（从相册）方法
function didPressChooesImage(that) {
    // 详情请见demo部分 index.js
}

// 文件上传（从客户端会话）方法，支持图片、视频、其余文件 (PDF(.pdf), Word(.doc/.docx), Excel(.xls/.xlsx), PowerPoint(.ppt/.pptx)等文件格式)
function didPressChooesMessageFile(that) {
    // 详情请见demo部分 index.js
}

// 在线查看文件，支持的文件格式：pdf, doc, docx, xls, xlsx, ppt, pptx。关于wx.openDocument方法，详情请参考微信官方文档：https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.openDocument.html
function didPressViewFileOnline(that) {
    // 详情请见demo部分 index.js
}

3. TypeScript 支持

// 请先参照微信小程序开发文档配置 TypeScript 支持
import { upload } from 'qiniuUploader.ts';

Page({
  didPressChooseImage: function() {
    wx.chooseImage({
      count: 1,
      success: function (res) {
        var filePath = res.tempFilePaths[0];
        upload({
          filePath: filePath,
          options: {
            key: '',          // 可选
            region: '',       // 可选(默认为'ECN')
            domain: '',
            uptoken: '',      // 以下三选一
            uptokenURL: '',
            uptokenFunc: () => {
              return '[yourTokenString]';
            },
            shouldUseQiniuFileName: true // 默认true
          },
          before: () => {
            // 上传前
            console.log('before upload');
          },
          success: (res) => {
            that.setData({
          		'imageObject': res
        		});
            console.log('file url is: ' + res.fileUrl);
          },
          fail: (err) => {
            console.log('error:' + err);
          },
          progress: (res) => {
            console.log('上传进度', res.progress)
            console.log('已经上传的数据长度', res.totalBytesSent)
            console.log('预期需要上传的数据总长度', res.totalBytesExpectedToSend)
          },
          complete: (err) => {
            // 上传结束
            console.log('upload complete');
          }
        });
      }
    });
  }
})

DEMO

请使用微信web开发者工具打开 demo 文件夹，然后配置 index.js 中的相关参数以使用 demo。

API

var options = {
  // bucket所在区域，这里是华北区。ECN, SCN, NCN, NA, ASG，分别对应七牛云的：华东，华南，华北，北美，新加坡 5 个区域
  region: 'NCN',

  // 获取uptoken方法三选一即可，执行优先级为：uptoken > uptokenURL > uptokenFunc。三选一，剩下两个置空。推荐使用uptokenURL，详情请见 README.md
  // 由其他程序生成七牛云uptoken，然后直接写入uptoken
  uptoken: '',
  // 从指定 url 通过 HTTP GET 获取 uptoken，返回的格式必须是 json 且包含 uptoken 字段，例如： {"uptoken": "0MLvWPnyy..."}
  uptokenURL: 'https://[yourserver.com]/api/uptoken',
  // uptokenFunc 这个属性的值可以是一个用来生成uptoken的函数，详情请见 README.md
  uptokenFunc: function () {
    // do something
    return qiniuUploadToken;
  },

  // bucket 外链域名，下载资源时用到。如果设置，会在 success callback 的 res 参数加上可以直接使用的 fileURL 字段。否则需要自己拼接
  domain: 'http://[yourBucketId].bkt.clouddn.com',
  // qiniuShouldUseQiniuFileName 如果是 true，则文件的 key 由 qiniu 服务器分配（全局去重）。如果是 false，则文件的 key 使用微信自动生成的 filename。出于初代sdk用户升级后兼容问题的考虑，默认是 false。
  // 微信自动生成的 filename较长，导致fileURL较长。推荐使用{qiniuShouldUseQiniuFileName: true} + "通过fileURL下载文件时，自定义下载名" 的组合方式。
  // 自定义上传key 需要两个条件：1. 此处shouldUseQiniuFileName值为false。 2. 通过修改qiniuUploader.upload方法传入的options参数，可以进行自定义key。（请不要直接在sdk中修改options参数，修改方法请见demo的index.js）
  // 通过fileURL下载文件时，文件自定义下载名，请参考：七牛云“对象存储 > 产品手册 > 下载资源 > 下载设置 > 自定义资源下载名”（https://developer.qiniu.com/kodo/manual/1659/download-setting）。本sdk在README.md的"常见问题"板块中，有"通过fileURL下载文件时，自定义下载名"使用样例。
  shouldUseQiniuFileName: false
};

// 图片上传（从相册）方法
function didPressChooesImage(that) {
    // 详情请见demo部分 index.js
}

// 文件上传（从客户端会话）方法，支持图片、视频、其余文件 (PDF(.pdf), Word(.doc/.docx), Excel(.xls/.xlsx), PowerPoint(.ppt/.pptx)等文件格式)
function didPressChooesMessageFile(that) {
    // 详情请见demo部分 index.js
}

// 在线查看文件，支持的文件格式：pdf, doc, docx, xls, xlsx, ppt, pptx。关于wx.openDocument方法，详情请参考微信官方文档：https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.openDocument.html
function didPressViewFileOnline(that) {
    // 详情请见demo部分 index.js
}

说明

1. 对于存储空间的存储区域，创建存储空间的时候可以选择。

   1. 当前一共有 5 个区域可以选择：[华东，华北，华南，北美，新加坡]，对应着不同的服务器地址
   2. 如果你不知道在哪里看当前空间的存储区域，可以登录七牛后台，在这个页面的右下角查看
   3. 对于存储区域和 options 中 region 代码可以参考这个表格

2. SDK 依赖 uptoken，可以直接设置 uptoken  、通过提供 Ajax 请求地址 uptokenURL 或者通过提供一个能够返回 uptoken 的函数 uptokenFunc 实现。

   var options = {
     // bucket所在区域，这里是华北区。ECN, SCN, NCN, NA, ASG，分别对应七牛云的：华东，华南，华北，北美，新加坡 5 个区域
     region: 'NCN',
   
     // 获取uptoken方法三选一即可，执行优先级为：uptoken > uptokenURL > uptokenFunc。三选一，剩下两个置空。推荐使用uptokenURL，详情请见 README.md
     // 由其他程序生成七牛云uptoken，然后直接写入uptoken
     uptoken: '',
     // 从指定 url 通过 HTTP GET 获取 uptoken，返回的格式必须是 json 且包含 uptoken 字段，例如： {"uptoken": "0MLvWPnyy..."}
     uptokenURL: 'https://[yourserver.com]/api/uptoken',
     // uptokenFunc 这个属性的值可以是一个用来生成uptoken的函数，详情请见 README.md
     uptokenFunc: function () { 
     	// do something
       return qiniuUploadToken;
     },
   
     // bucket 外链域名，下载资源时用到。如果设置，会在 success callback 的 res 参数加上可以直接使用的 fileURL 字段。否则需要自己拼接
     domain: 'http://[yourBucketId].bkt.clouddn.com',
     // qiniuShouldUseQiniuFileName 如果是 true，则文件的 key 由 qiniu 服务器分配（全局去重）。如果是 false，则文件的 key 使用微信自动生成的 filename。出于初代sdk用户升级后兼容问题的考虑，默认是 false。
     // 微信自动生成的 filename较长，导致fileURL较长。推荐使用{qiniuShouldUseQiniuFileName: true} + "通过fileURL下载文件时，自定义下载名" 的组合方式。
     // 自定义上传key 需要两个条件：1. 此处shouldUseQiniuFileName值为false。 2. 通过修改qiniuUploader.upload方法传入的options参数，可以进行自定义key。（请不要直接在sdk中修改options参数，修改方法请见demo的index.js）
     // 通过fileURL下载文件时，文件自定义下载名，请参考：七牛云“对象存储 > 产品手册 > 下载资源 > 下载设置 > 自定义资源下载名”（https://developer.qiniu.com/kodo/manual/1659/download-setting）。本sdk在README.md的"常见问题"板块中，有"通过fileURL下载文件时，自定义下载名"使用样例。
     shouldUseQiniuFileName: false
   };

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

   例如：七牛云 java sdk 中提到了魔法变量 可以指定上传文件后，返回对象中包含字段：文件的大小 fsize , 文件类型 mimeType 等。

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

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

常见问题

1. 关于上传key

   如果在上传的时候没有指定文件 key，会使用 wx.chooesImage 得到的 tmp filePath 作为文件的 key。例如：tmp_xxxxxxx.jpg。

   或者，可以使用由 qiniu 服务器分配的 key （全局去重）。例如： Fh6qfpY... （建议的方式）

   微信自动生成的 filename较长，导致fileURL较长。推荐使用{qiniuShouldUseQiniuFileName: true} + "通过fileURL下载文件时，自定义下载名" 的组合方式。

   详情请见demo的 index.js 中的 shouldUseQiniuFileName 属性，sdk中的 qiniuShouldUseQiniuFileName 属性。

2. 设置取消上传、暂停上传：

   请见demo部分，index.js中data.cancelTask。sdk的qiniuUploader.js中的cancelTask方法。

   此外，demo页面有中断上传的UI演示。

3. 限制上传文件的类型：

   支持图片文件、视频文件、其它文件（PDF(.pdf), Word(.doc/.docx), Excel(.xls/.xlsx), PowerPoint(.ppt/.pptx)等文件格式）。

   demo部分的 index.wxml 页面有图片上传（从相册）、文件上传（从客户端会话）的UI演示。

4. 通过fileURL下载文件时，自定义下载名

   请参考：七牛云“对象存储 > 产品手册 > 下载资源 > 下载设置 > 自定义资源下载名”（https://developer.qiniu.com/kodo/manual/1659/download-setting） 例如：fileUrl为 http://xxx.com/keyyyyy，直接在浏览器中打开此链接下载的文件，文件名为“keyyyyy”。

   想自定义下载得到的文件名为“myName”，可以通过：http://xxx.com/keyyyyy?attname=myName 来下载，即 "fileUrl" + "?attname=" + "自定义文件名" 的方式。

贡献代码

1. 登录 https://github.com

2. Fork [email protected]:gpake/qiniu-wxapp-sdk.git

3. 创建您的特性分支 (git checkout -b new-feature)

4. 提交您的改动 (git commit -am 'Added some features or fixed a bug')

5. 将您的改动记录提交到远程 git 仓库 (git push origin new-feature)

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

基于 GPL V3 协议发布:

GPL V3 LICENSE