qiniu wxapp sdk下載 - qiniu wxapp sdk源碼下載

qiniu wxapp sdk

Ai源碼

1.0.0

下載

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=" + "自訂檔案名稱" 的方式。