Qiniu-wxapp-SDK

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

快速导航

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

概述

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 上传地址添加到小程序的访问白名单中，方法如下：

登录微信公众平台，前往 设置 - 开发设置，点击 服务器配置 下的「修改」链接。

修改 uploadFile 域名(比如华东 https 上传地址为：https://up.qiniup.com，地址不清楚写什么请参见https地址附录)

如果需要下载文件，则还需要一同设置 downloadFile 域名，为你的 bucket 下载地址

保存即可

字段名	内容
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按钮绑定的事件开始看，注释写的很详细。

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

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

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

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
}

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

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
};

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

例如：七牛云 java sdk 中提到了魔法变量可以指定上传文件后，返回对象中包含字段：文件的大小 fsize , 文件类型 mimeType 等。
如果您想了解更多七牛的图片处理，建议您仔细阅读七牛官方文档-图片处理
SDK 示例生成 uptotken 时，指定的 Bucket Name 为公开空间，所以可以公开访问上传成功后的资源。若您生成 uptoken 时，指定的 Bucket Name 为私有空间，那您还需要在服务端进行额外的处理才能访问您上传的资源。具体参见下载凭证。SDK 数据处理部分功能不适用于私有空间。

常见问题

关于上传key

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

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

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

详情请见demo的 index.js 中的 shouldUseQiniuFileName 属性，sdk中的 qiniuShouldUseQiniuFileName 属性。
设置取消上传、暂停上传：

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

此外，demo页面有中断上传的UI演示。
限制上传文件的类型：

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

demo部分的 index.wxml 页面有图片上传（从相册）、文件上传（从客户端会话）的UI演示。
通过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=" + "自定义文件名" 的方式。

贡献代码

登录 https://github.com
Fork git@github.com:gpake/qiniu-wxapp-sdk.git
创建您的特性分支 (git checkout -b new-feature)
提交您的改动 (git commit -am 'Added some features or fixed a bug')
将您的改动记录提交到远程 git 仓库 (git push origin new-feature)
然后到 github 网站的该 git 远程仓库的 new-feature 分支下发起 Pull Request

基于 GPL V3 协议发布:

GPL V3 LICENSE

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Qiniu-wxapp-SDK

快速导航

最近一次修改：

概述

功能简介

准备

安装

使用

上传功能

DEMO

API

说明

常见问题

贡献代码

基于 GPL V3 协议发布:

Files

README.md

Latest commit

History

README.md

File metadata and controls

Qiniu-wxapp-SDK

快速导航

最近一次修改：

概述

功能简介

准备

安装

使用

上传功能

DEMO

API

说明

常见问题

贡献代码

基于 GPL V3 协议发布: