/qiniu-wxapp-sdk

qiniu SDK based on wxapp

Primary LanguageJavaScriptGNU General Public License v3.0GPL-3.0

Qiniu-wxapp-SDK

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

快速导航

最近一次修改：

  • 增加了文件在线查看功能，支持的文件格式：支持的文件格式：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中暂时没有包含这部分。

功能简介

  • 上传文件，支持图片文件、视频文件、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，可以通过以下二种方式实现：

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

后端服务应提供一个 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");
  1. 在需要使用上传功能的页面，开心地使用：
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
}
  1. 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 git@github.com: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