qiniu wxapp sdk
1.0.0
WeChat Mini Program SDK developed based on Qiniu Cloud API
Qiniu-wxapp-SDK is the implementation of Qiniu Cloud on the mini program. The network functions rely on the WeChat mini program API. You can easily upload files to Qiniu Cloud in the mini program based on the SDK.
Qiniu-wxapp-SDK is a client SDK and does not include token generation implementation. For security reasons, it is recommended to obtain the token from the server through the network. For specific generation code, please refer to the following server SDK documentation. This part is not currently included in the SDK Demo.
Other features are under development, so stay tuned.
Download qiniuUploader.js from github and import the mini program project.
Before using the SDK, you must first register a Qiniu Cloud account and log in to the console to obtain a pair of valid AccessKey and SecretKey. You can read How to Access Qiniu and Security Mechanism to learn more about how to use and manage keys correctly.
The SDK relies on the server to issue uptoken, which can be achieved in the following two ways:
You need to know which region your Qiniu存储空间is set in, such as East China, South China, etc., see Regional Settings
The backend service should provide a URL address for the applet to request the address and obtain the uptoken. After the request is successful, the server should return json in the following format (including at least the uptoken field):
{
"uptoken": "0MLvWPnyya1WtPnXFy9KLyGHyFPNdZceomL..."
}
According to the Qiniu存储空间you created, add the corresponding https upload address to the access whitelist of the mini program. The method is as follows:
- Log in to the WeChat public platform, go to Settings - Development Settings , and click the " Modify " link under Server Configuration .
- Modify the uploadFile domain name (for example, the East China https upload address is:
https://up.qiniup.com. If you don’t know what to write in the address, please refer to the https address appendix)- If you need to download a file, you also need to set the downloadFile domain name as your bucket download address.
- Just save it
| Field name | content |
|---|---|
| request domain name | https://yourServce.com |
| uploadFile domain name | https://up.qiniup.com (fill in according to storage area) |
| downloadFile domain name | https://baldkf.bkt.clouddn.com |
Qiniu Cloud file upload interface, files are transferred to the matching interface, and the storage area corresponds to the HTTPS address. Please refer to the official documentation.
| storage area | area code | HTTPS address |
|---|---|---|
| East China | ECN | https://up.qiniup.com |
| North China | NCN | https://up-z1.qiniup.com |
| South China | SCN | https://up-z2.qiniup.com |
| North America | NA | https://up-na0.qiniup.com |
| Singapore | ASG | https://up-as0.qiniup.com |
Note!! WeChat currently limits the domain name whitelist to only three modifications per month.
Temporarily supports one installation method
Clone the repository directly
git clone https://github.com/gpake/qiniu-wxapp-sdk.git
The qiniuUploader.js and qiniuUploader.ts files are in the sdk directory of this project.
It is recommended to refer to the usage of the demo and start by uploading the events bound to the UI buttons on the index.wxml page of the demo. The comments are very detailed.
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 支持
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' ) ;
}
} ) ;
}
} ) ;
}
} )Please use WeChat web developer tools to open the demo folder, and then configure the relevant parameters in index.js to use the demo.
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
}The storage area of the storage space can be selected when creating the storage space.
The SDK relies on uptoken , which can be set directly, by providing the Ajax request address uptokenURL , or by providing a function uptokenFunc that can return uptoken.
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
} ;If you want to know more about Qiniu's upload strategy, it is recommended that you carefully read Qiniu's official documentation - Upload. Qiniu's upload strategy is specified in the back-end service.
For example: Qiniuyun java sdk mentioned that magic variables can specify that after uploading a file, the returned object contains fields: file size fsize , file type mimeType etc.
If you want to know more about Qiniu's image processing, it is recommended that you carefully read Qiniu's official documentation - Image Processing
When the SDK example generates uptotken, the specified Bucket Name is a public space, so the resources after successful upload can be publicly accessed. If Bucket Name specified when you generate the uptoken is a private space, you will need to perform additional processing on the server to access the resources you uploaded. For details, see Downloading Certificates. Some SDK data processing functions are not applicable to private spaces.
About uploading keys
If the file key is not specified when uploading, the tmp filePath obtained by wx.chooesImage will be used as the file key. For example: tmp_xxxxxxx.jpg .
Alternatively, you can use the key assigned by the qiniu server (global deduplication). For example: Fh6qfpY... (recommended way)
The filename automatically generated by WeChat is longer, resulting in a longer fileURL. It is recommended to use the combination of {qiniuShouldUseQiniuFileName: true} + "When downloading files through fileURL, customize the download name".
For details, please see shouldUseQiniuFileName attribute in the demo's index.js and the qiniuShouldUseQiniuFileName attribute in the sdk.
Set to cancel upload and pause upload:
Please see the demo section, data.cancelTask in index.js . The cancelTask method in qiniuUploader.js of sdk.
In addition, the demo page has a UI demonstration that interrupts uploading.
Limit the types of uploaded files:
Supports image files, video files, and other files (PDF (.pdf), Word (.doc/.docx), Excel (.xls/.xlsx), PowerPoint (.ppt/.pptx) and other file formats).
The index.wxml page in the demo section has UI demonstrations for image upload (from the album) and file upload (from the client session).
When downloading files through fileURL, customize the download name
Please refer to: Qiniu Cloud "Object Storage > Product Manual > Download Resources > Download Settings > Custom Resource Download Name" (https://developer.qiniu.com/kodo/manual/1659/download-setting) For example: fileUrl is http://xxx.com/keyyyyy , open the file downloaded from this link directly in the browser, the file name is "keyyyyy".
If you want to customize the name of the downloaded file as "myName", you can download it through: http://xxx.com/keyyyyy?attname=myName , that is, "fileUrl" + "?attname=" + "custom file name" Way.
Log in to https://github.com
Fork [email protected]:gpake/qiniu-wxapp-sdk.git
Create your feature branch (git checkout -b new-feature)
Commit your changes (git commit -am 'Added some features or fixed a bug')
Submit your change record to the remote git repository (git push origin new-feature)
Then go to the github website and initiate a Pull Request under the new-feature branch of the git remote repository.
GPL V3 LICENSE
