概述

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

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

Java

PHP

Python

Ruby

Go

Node.js

C#

C/C++

功能简介

上传

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

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

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

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

利用七牛服务端 SDK 构建后端服务(建议的方式)

利用七牛底层 API 构建服务，详见七牛上传策略和上传凭证

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

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

{

"uptoken": "0MLvWPnyya1WtPnXFy9KLyGHyFPNdZceomL..."

}

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

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

修改 uploadFile 域名(比如华北 https 上传地址为：https://up-z1.qbox.com，地址不清楚请参见https地址附录)

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

保存即可

字段名

内容

request 域名

https://yourServce.com

uploadFile 域名

https://up.qbox.me (根据存储区域填写)

downloadFile 域名

https://baldkf.bkt.clouddn.com

存储区域对应 HTTPS 地址，参考官方文档

存储区域

区域代码

HTTPS 地址

华东

ECN

https://up.qbox.me

华北

NCN

https://up-z1.qbox.me

华南

SCN

https://up-z2.qbox.me

北美

NA

https://up-na0.qbox.me

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

安装

暂时支持一种安装方式

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

直接克隆仓库

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

qiniuUploader.js 文件在 sdk 目录。使用

上传功能

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

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

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

Page({

didPressChooseImage: function() {

var that = this;

// 选择图片

wx.chooseImage({

count: 1,

success: function (res) {

var filePath = res.tempFilePaths[0];

// 交给七牛上传

qiniuUploader.upload(filePath, (res) => {

// 每个文件上传成功后,处理相关的事情

// 其中 info 是文件上传成功后，服务端返回的json，形式如

// {

//    "hash": "Fh8xVqod2MQ1mocfI4S4KpRL6D98",

//    "key": "gogopher.jpg"

//  }

// 参考http://developer.qiniu.com/docs/v6/api/overview/up/response/simple-response.html

that.setData({

'imageURL': res.imageURL,

});

}, (error) => {

console.log('error: ' + error);

}, {

uploadURL: 'https://up.qbox.me',

domain: 'bzkdlkaf.bkt.clouddn.com', // // bucket 域名，下载资源时用到。如果设置，会在 success callback 的 res 参数加上可以直接使用的 ImageURL 字段。否则需要自己拼接

key: 'customFileName.jpg', // 自定义文件 key。如果不设置，默认为使用微信小程序 API 的临时文件名

// 以下方法三选一即可，优先级为：uptoken > uptokenURL > uptokenFunc

uptoken: 'xxxxxxxxUpToken', // 由其他程序生成七牛 uptoken

uptokenURL: 'UpTokenURL.com/uptoken', // 从指定 url 通过 HTTP GET 获取 uptoken，返回的格式必须是 json 且包含 uptoken 字段，例如： {"uptoken": "0MLvWPnyy..."}

uptokenFunc: function() {return 'zxxxzaqdf';}

});

}

})

}

});

// domain 为七牛空间(bucket)对应的域名，选择某个空间后，可通过"空间设置->基本设置->域名设置"查看获取

// key：通过微信小程序 Api 获得的图片文件的 URL 已经是处理过的临时地址，可以作为唯一文件 key 来使用。

DEMO

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

API

var options = {

region: 'East', // 是你注册bucket的时候选择的区域的代码

// ECN, SCN, NCN, NA，分别对应七牛的：华东，华南，华北，北美四个区域

// 详情可以参见「说明」部分的第一条

domain: 'bzkdlkaf.bkt.clouddn.com', // // bucket 域名，下载资源时用到。如果设置，会在 success callback 的 res 参数加上可以直接使用的 ImageURL 字段。否则需要自己拼接

// 以下方法三选一即可，优先级为：uptoken > uptokenURL > uptokenFunc

uptoken: 'xxxxxxxxUpToken', // 由其他程序生成七牛 uptoken

uptokenURL: 'UpTokenURL.com/uptoken', // 从指定 url 通过 HTTP GET 获取 uptoken，返回的格式必须是 json 且包含 uptoken 字段，例如： {"uptoken": "0MLvWPnyy..."}

uptokenFunc: function() {

// do something to make a uptoken

return 'zxxxzaqdfUpToken';

}

};

qiniuUploder.init(options);

// 如果使用了 init 方法，则 upload 函数的 options 可以省略。如果没有 init，upload 中也没有 options 则会报错。

// 这里的 options 和 init 中的传入参数一样，只会修改传入的参数

// 上传之前会检查 uptoken 是否存在

qiniuUploader.upload(wxappFilePath, [succeedCallback, [failedCallback, [options]]]);

// 其中 wxappFilePath，是通过微信小程序官方 API：wx.chooseImage，在 success callback得到 var filePath = res.tempFilePaths[0];

说明

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

当前一共有四个区域可以选择：[华东，华北，华南，北美]，对应着不同的服务器地址

如果你不知道在哪里看当前空间的存储区域，可以登录七牛后台，在这个页面的右下角查看

对于存储区域和 options 中 region 代码可以参考这个表格

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

如果没用设置过uptoken, uptoken_url 两个参数中必须有一个被设置

如果提供了多个，其优先级为 uptoken > uptoken_url

其中 uptoken 是直接提供上传凭证，uptoken_url 是提供了获取上传凭证的地址

uptoken : '', // uptoken 是上传凭证，由其他程序生成

uptoken_url: '/uptoken',         // Ajax 请求 uptoken 的 Url，强烈建议设置(服务端提供)

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

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

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

常见问题

关于上传文件名

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

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

微信小程序上传 API 暂时无法取消、暂停上传操作

限制上传文件的类型：

使用微信小程序 API 只能选到图片文件。

如果是小程序内产生的文件，那么正常使用即可。