Qiniu-JavaScript-SDK
Start
npm install --save qiniu-js-es6
调用
import qiniu from 'qiniu-js-es6'
原始介绍
基于七牛 API 及 Plupload 开发的前端 JavaScript SDK
快速导航
概述
Qiniu-JavaScript-SDK (下文简称为 JS-SDK)适用于 IE8+、Chrome、Firefox、Safari 等浏览器,基于七牛云存储官方 API 构建,其中上传功能基于 Plupload 插件封装。开发者基于 JS-SDK 可以方便的从浏览器端上传文件至七牛云存储,并对上传成功后的图片进行丰富的数据处理操作。
不考虑兼容性的情况下,如手机端,建议直接使用 Formdata 结合七牛表单上传的方式上传文件。
Formdata 上传 demo
Qiniu-JavaScript-SDK 为客户端 SDK,没有包含 token 生成实现,为了安全,token 建议通过网络从服务端获取,具体生成代码可以参考以下服务端 SDK 的文档。
Qiniu-JavaScript-SDK 的示例 Demo 中的服务器端部分是基于 Node.js 服务器端 SDK 开发的。
功能简介
- 上传
- html5 模式大于 4M 时可分块上传,小于4M时直传
- 分块上传时,可以断点续上传
- flash、html4 模式直接上传
- 继承了 plupload 的功能,可筛选文件上传、拖曳上传等
- 下载(公开资源)
- 数据处理(图片)
- imageView2(缩略图)
- imageMogr2(高级处理,包含缩放、裁剪、旋转等)
- imageInfo (获取基本信息)
- exif (获取图片 EXIF 信息)
- watermark (文字、图片水印)
- pipeline (管道,可对 imageView2、imageMogr2、watermark 进行链式处理)
项目构成介绍
├── demo // 示例 Demo
│ ├── images
│ │ └── ...
│ ├── scripts
│ │ └── ...
│ ├── styles
│ │ └── ...
│ ├── views
│ │ └── ...
│ ├── config.js.example
│ └── server.js // 示例 Demo 的服务器端程序
├── dist // SDK 输出目录
│ ├── qiniu.js // 非压缩版
│ ├── qiniu.min.js // 压缩版
│ └── qiniu.min.map // 压缩版的 source map 文件
├── src // SDK 源目录
│ └── qiniu.js // 源文件
├── Gruntfile.js
├── Makefile
├── README.md
├── bower.json
└── package.json
准备
-
JS-SDK 的上传功能基于 Plupload 插件封装的,所以需要下载 Plupload。
您也可以访问 开放静态文件 CDN ,搜索 plupload,使用 CDN 加速的静态文件地址。
-
在使用 JS-SDK 之前,您必须先注册一个七牛帐号,并登录控制台获取一对有效的 AccessKey 和 SecretKey,您可以阅读 快速入门 和 安全机制 以进一步了解如何正确使用和管理密钥 。
-
JS-SDK 依赖服务端颁发 uptoken,可以通过以下二种方式实现:
后端服务应提供一个 URL 地址,供 JS-SDK 初始化使用,前端通过 Ajax 请求该地址后获得 uptoken。Ajax 请求成功后,服务端应返回如下格式的 json:
{
"uptoken": "0MLvWPnyya1WtPnXFy9KLyGHyFPNdZceomL..."
}
安装
支持以下几种安装方式
-
直接使用CDN 加速的静态文件地址,访问 开放静态文件 CDN ,搜索 qiniu
https://cdn.staticfile.org/qiniu-JS-SDK/<version>/qiniu.min.js
-
使用 Bower 安装
Bower 是一个客户端技术的软件包管理器,它可用于搜索、安装和卸载如 JavaScript、HTML、CSS 之类的网络资源。如果需要更详细的关于 Bower 的使用说明,您可以访问 Bower 官方网站。
通过 Bower 安装会将 JS-SDK 依赖的 plupload 也一起安装在 bower_components
中:
bower install qiniu
执行之后,JS-SDK 和 plupload 分别在以下位置
bower_components
├── plupload
│ └── js
│ ├── moxie.js
│ ├── moxie.min.js
│ ├── plupload.dev.js
│ ├── plupload.full.min.js
│ └── plupload.min.js
└── qiniu
└── dist
├── qiniu.js
├── qiniu.min.js
└── qiniu.min.map
-
使用 NPM 安装
NPM 的全称是 Node Package Manager,是一个 NodeJS 包管理和分发工具,已经成为了非官方的发布 Node 模块(包)的标准。如果需要更详细的关于 NPM 的使用说明,您可以访问 NPM 官方网站,或对应的中文网站
npm install qiniu-js
执行之后,JS-SDK 在以下位置
node_modules
└── qiniu-js
└── dist
├── qiniu.js
├── qiniu.min.js
└── qiniu.min.map
-
通过 Github 上的 qiniu/js-sdk 仓库获取
下载最新的 发布版本 并解压 或 直接克隆仓库
git clone https://github.com/qiniu/js-sdk.git
JS-SDK 在 dist
目录中
使用
上传功能
-
在页面中引入 plupload,plupload.full.min.js
(生产环境)或 引入plupload.dev.js
和moxie.js
(开发调试)
-
在页面中引入 qiniu.min.js
(生产环境)或 qiniu.js
(开发调试)
-
初始化 uploader,请确保在执行初始化时,页面已经引入 plupload
var uploader = Qiniu.uploader({
runtimes: 'html5,flash,html4',
browse_button: 'pickfiles',
get_new_uptoken: false,
domain: '<Your bucket domain>',
container: 'container',
max_file_size: '100mb',
flash_swf_url: 'path/of/plupload/Moxie.swf',
max_retries: 3,
dragdrop: true,
drop_element: 'container',
chunk_size: '4mb',
auto_start: true,
init: {
'FilesAdded': function(up, files) {
plupload.each(files, function(file) {
});
},
'BeforeUpload': function(up, file) {
},
'UploadProgress': function(up, file) {
},
'FileUploaded': function(up, file, info) {
},
'Error': function(up, err, errTip) {
},
'UploadComplete': function() {
},
'Key': function(up, file) {
var key = "";
return key
}
}
});
对上传成功的图片进行数据处理
-
watermark(水印)
var imgLink = Qiniu.watermark({
mode: 1,
image: 'http://www.b1.qiniudn.com/images/logo-2.png',
dissolve: 50,
gravity: 'SouthWest',
dx: 100,
dy: 100
}, key);
或
var imgLink = Qiniu.watermark({
mode: 2,
text: 'hello world !',
dissolve: 50,
gravity: 'SouthWest',
fontsize: 500,
font: '黑体',
dx: 100,
dy: 100,
fill: '#FFF000'
}, key);
具体水印参数解释见水印(watermark)
-
imageView2
var imgLink = Qiniu.imageView2({
mode: 3,
w: 100,
h: 100,
q: 100,
format: 'png'
}, key);
具体缩略参数解释见图片基本处理(imageView2)
-
imageMogr2
var imgLink = Qiniu.imageMogr2({
auto-orient: true,
strip: true,
thumbnail: '1000x1000'
crop: '!300x400a10a10',
gravity: 'NorthWest',
quality: 40,
rotate: 20,
format: 'png',
blur:'3x5'
}, key);
具体高级图像处理参数解释见图像高级处理(imageMogr2)
-
imageInfo
var imageInfoObj = Qiniu.imageInfo(key);
具体 imageInfo 解释见图片基本信息(imageInfo)
Ajax跨域限制,IE系列此函数只支持IE10+
-
exif
var exifOjb = Qiniu.exif(key);
具体 exif 解释见图片EXIF信息(exif)
Ajax跨域限制,IE系列此函数只支持IE10+
-
pipeline(管道操作)
var fopArr = [{
fop: 'watermark',
mode: 2,
text: 'hello world !',
dissolve: 50,
gravity: 'SouthWest',
fontsize: 500,
font : '黑体',
dx: 100,
dy: 100,
fill: '#FFF000'
},{
fop: 'imageView2',
mode: 3,
w: 100,
h: 100,
q: 100,
format: 'png'
},{
fop: 'imageMogr2',
auto-orient: true,
strip: true,
thumbnail: '1000x1000'
crop: '!300x400a10a10',
gravity: 'NorthWest',
quality: 40,
rotate: 20,
format: 'png',
blur:'3x5'
}];
var imgLink = Qiniu.pipeline(fopArr, key));
具体管道操作解释见管道操作
运行示例
-
进入项目根目录,执行 make install
或 npm install & bower install
安装依赖第三方库
-
进入 demo
目录,按照目录下的 config.example
示例,创建 config.js
文件,其中,Access Key
和 Secret Key
按如下方式获取
module.exports = {
'ACCESS_KEY': '<Your Access Key>',
'SECRET_KEY': '<Your Secret Key>',
'Bucket_Name': '<Your Bucket Name>',
'Port': 19110,
'Uptoken_Url': '<Your Uptoken_Url>',
'Domain': '<Your Bucket Domain>'
}
-
进入项目根目录,执行 make dev
或 node demo/server.js
访问命令行打印出的 demo 地址。
说明
-
JS-SDK 依赖 Plupload,初始化之前请引入 Plupload。
-
JS-SDK 依赖 uptoken,可以直接设置 uptoken
、通过提供 Ajax 请求地址 uptoken_url
或者通过提供一个能够返回 uptoken 的函数 uptoken_func
实现。
-
如果您想了解更多七牛的上传策略,建议您仔细阅读 七牛官方文档-上传。
另外,七牛的上传策略是在后端服务指定的,JS-SDK 的 setOption API 只是设置 Plupload 的初始化参数,和上传策略无关。
-
如果您想了解更多七牛的图片处理,建议您仔细阅读 七牛官方文档-图片处理
-
如果是 https 网站,上传地址为 https://up.qbox.me 否则使用 http://upload.qiniu.com
-
JS-SDK 示例生成 uptotken 时,指定的 Bucket Name
为公开空间,所以可以公开访问上传成功后的资源。若您生成 uptoken 时,指定的 Bucket Name
为私有空间,那您还需要在服务端进行额外的处理才能访问您上传的资源。具体参见下载凭证。JS-SDK 数据处理部分功能不适用于私有空间。
常见问题
七牛提供基于 plupload 插件封装上传的 demo http://jssdk.demo.qiniu.io/
,如果不需要 plupload 插件可以参考 https://github.com/iwillwen/qiniu.js/tree/develop
,这里主要针对基于 plupload 插件的方式讲解遇到的一些问题,通过参考 plupload 文档资料,可以对七牛的 demo 进行修改,以满足自己的业务需求,plupload 插件的使用文档可以参考 http://www.cnblogs.com/2050/p/3913184.html
1. 关于上传文件命名问题,可以参考:
在 main.js 里面,unique_names 是 plupload 插件下面的一个参数,当值为 true 时会为每个上传的文件生成一个唯一的文件名,这个是 plupload 插件自动生成的,如果设置成 false,七牛这边是会以上传的原始名进行命名的。
- 上传的 scope 为 bucket 的形式,unique_names 参数设置为false,上传后文件的 key 是本地的文件名 abc.txt
- 上传的 scope 为 bucket 的形式,unique_names 参数设置为 true,plupload 插件会忽略本地文件名,而且这个命名也是没有规律的,上传后文件的 key 是 plupload 插件生成的,比如 Yc7DZRS1m73o.txt。
- 上传的 scope 为 bucket:key 的形式,上传文件本地的名字需要和 scope 中的 key 是一致的,不然会报错 key doesn‘t match with scope, 注意,这种形式是不能设置 unique_names 为 true 的,因为即使上传文件本地名字为 abc.txt,但是 plupload 会给这个文件赋值另外一个文件名。
- 上传的 scope 为 bucket,但是 token 中有设定 saveKey,这种形式 save_key 是应该设置为 true,并且上传的本地文件名也是需要和这个 savekey 文件名一致的。
- 通过 JS 前端设置上传的 key,在 main.js 文件里面设置如下:
'Key': function(up, file) {
var key = "";
// do something with key
return key
}
这个默认是注释的,若想在前端对每个文件的 key 进行个性化处理,可以配置该函数
该配置必须要在 unique_names: false , save_key: false 时才生效
取消注释后,其优先级要高于:qiniu.js 文件中 getFileKey。
2. 设置自定义预览样式
// 该设置在ui.js 文件里,默认为
var imageView =‘?imageView2/1/w/100/h/100’
// 可修改成
var imageView = ‘样式符+样式名’
3. 关于设置取消上传可以参考:
http://stackoverflow.com/questions/11014384/cancel-file-upload-listener
(文件 plupload.dev.js 1950行 removeFile : function(file) 方法)
4. 限制上传文件的类型:
这里又分为两种方法:
- 通过在 token 中设定 mimeLimit 字段限定上传文件的类型,示例
“image/*“ 表示只允许上传图片类型;
“image/jpeg;image/png” 表示只允许上传 jpg 和 png 类型的图片;
“!application/json;text/plain” 表示禁止上传 json 文本和纯文本。(注意最前面的感叹号)
- 通过 plupload 中设定 filter 参数直接在 JS 前端限定,如下
// 可以使用该参数来限制上传文件的类型,大小等,该参数以对象的形式传入,它包括三个属性:
filters : {
max_file_size : '100mb',
prevent_duplicates: true,
// Specify what files to browse for
mime_types: [
{title : "flv files", extensions : "flv"} // 限定flv后缀上传格式上传
{title : "Video files", extensions : "flv,mpg,mpeg,avi,wmv,mov,asf,rm,rmvb,mkv,m4v,mp4"}, // 限定flv,mpg,mpeg,avi,wmv,mov,asf,rm,rmvb,mkv,m4v,mp4后缀格式上传
{title : "Image files", extensions : "jpg,gif,png"}, // 限定jpg,gif,png后缀上传
{title : "Zip files", extensions : "zip"} // 限定zip后缀上传
]
},
5. 设置每次只能选择一个文件
通过 plupload 插件中的 multi_selection 参数控制,如下
// 设置一次只能选择一个文件
multi_selection: false,
6. 设置取消上传,暂停上传
在 index.html 中加入者两个控制按钮:
<a class="btn btn-default btn-lg " id="up_load" href="#" >
<span>确认上传</span>
</a>
<a class="btn btn-default btn-lg " id="stop_load" href="#" >
<span>暂停上传</span>
</a>
然后在 main.js 文件里面绑定这两个按钮,添加代码如下:
$('#up_load').on('click', function(){
uploader.start();
});
$('#stop_load').on('click', function(){
uploader.stop();
});
7. 取消分片上传
将 main.js 里面 chunk_size: '4mb'
设置 chunk_size: '0mb'
,注意分片上传默认也只能是 4M,如果设置一个别的分片的大小会出现上传失败。
8. 取消自动上传
将 main.js 文件 auto_start
参数改成 auto_start: false
9. 关于请求 token 出现跨域
因为都是建议用户从后端 SDK 获取 token,然后在 main.js 设置参数 uptoken_url: '获取uptoken的url', 这里就有可能出现跨域的现象,此时在服务端添加 response.setHeader("Access-Control-Allow-Origin","*"); 相应头字段即可。
推荐一个关于 CORS 的网站
**10.Android自带的Webview对JS SDK不支持 **
在Android自带的Webview里面引用JS SDK的demo(http://jssdk.demo.qiniu.io/) :
public class MainActivity extends Activity {
private WebView webview;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
webview = (WebView) findViewById(R.id.wv);
webview.getSettings().setJavaScriptEnabled(true);
webview.setWebViewClient(new WebViewClient(){
public boolean shouldOverrideUrlLoading(WebView view, String url){
view.loadUrl(url);
return true;
}
});
webview.loadUrl("http://demos.qiniu.com/demo/simpleuploader/");
}
}
但是点击选择文件按钮没有反应,这个是Webview对JS不是很支持造成的,解决方法可以引入这个Webview,jar包地址如下:
https://github.com/delight-im/Android-AdvancedWebView/blob/master/JARs/Android-AdvancedWebView.jar
使用的方法文档上都有写,比较简单:
private AdvancedWebView mWebView;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
mWebView = (AdvancedWebView) findViewById(R.id.webview);
mWebView.setListener(this, this);
mWebView.loadUrl("http://jssdk.demo.qiniu.io/");
}
**11.关于多个按钮选择文件的Demo **
很多用户都在问JSSDK多文件选择的Demo,其实比较简单,只需要在main.js文件里面多new几个Uploader对象就可以了,然后在主页面上里面写好对应的上传的按钮就可以了
这里直接给出main.js和indxe.html里面需要改动的地方:
main.js里面多new几个uploader对象
$(function() {
var uploader = Qiniu.uploader({
runtimes: 'html5,flash,html4',
browse_button: 'pickfiles',
container: 'container',
drop_element: 'container',
max_file_size: '100mb',
flash_swf_url: 'js/plupload/Moxie.swf',
dragdrop: true,
chunk_size: '4mb',
uptoken:'um6IEH7mtwnwkGpjImD08JdxlvViuELhI4mFfoeL:79ApUIePTtKIdVGDHJ9D9BfBnhE=:eyJzY29wZSI6ImphdmFkZW1vIiwiZGVhZGxpbmUiOjE0NTk4ODMyMzV9Cg==',
// uptoken_url: $('#uptoken_url').val(), //当然建议这种通过url的方式获取token
domain: $('#domain').val(),
auto_start: false,
init: {
'FilesAdded': function(up, files) {
$('table').show();
$('#success').hide();
plupload.each(files, function(file) {
var progress = new FileProgress(file, 'fsUploadProgress');
progress.setStatus("等待...");
});
},
'BeforeUpload': function(up, file) {
var progress = new FileProgress(file, 'fsUploadProgress');
var chunk_size = plupload.parseSize(this.getOption('chunk_size'));
if (up.runtime === 'html5' && chunk_size) {
progress.setChunkProgess(chunk_size);
}
},
'UploadProgress': function(up, file) {
var progress = new FileProgress(file, 'fsUploadProgress');
var chunk_size = plupload.parseSize(this.getOption('chunk_size'));
progress.setProgress(file.percent + "%", file.speed, chunk_size);
},
'UploadComplete': function() {
$('#success').show();
},
'FileUploaded': function(up, file, info) {
var progress = new FileProgress(file, 'fsUploadProgress');
progress.setComplete(up, info);
},
'Error': function(up, err, errTip) {
$('table').show();
var progress = new FileProgress(err.file, 'fsUploadProgress');
progress.setError();
progress.setStatus(errTip);
}
}
});
uploader.bind('FileUploaded', function() {
console.log('hello man,a file is uploaded');
});
$('#up_load').on('click', function(){
uploader.start();
});
$('#stop_load').on('click', function(){
uploader.stop();
});
var Q2 = new QiniuJsSDK();
var uploader2 = Q2.uploader({
runtimes: 'html5,flash,html4',
browse_button: 'pickfiles2',
container: 'container2',
drop_element: 'container2',
max_file_size: '100mb',
flash_swf_url: 'js/plupload/Moxie.swf',
dragdrop: true,
chunk_size: '4mb',
uptoken:'um6IEH7mtwnwkGpjImD08JdxlvViuELhI4mFfoeL:79ApUIePTtKIdVGDHJ9D9BfBnhE=:eyJzY29wZSI6ImphdmFkZW1vIiwiZGVhZGxpbmUiOjE0NTk4ODMyMzV9Cg==',
// uptoken_url: $('#uptoken_url').val(), //当然建议这种通过url的方式获取token
domain: $('#domain').val(),
auto_start: false,
init: {
'FilesAdded': function(up, files) {
$('table').show();
$('#success').hide();
plupload.each(files, function(file) {
var progress = new FileProgress(file, 'fsUploadProgress');
progress.setStatus("等待...");
});
},
'BeforeUpload': function(up, file) {
var progress = new FileProgress(file, 'fsUploadProgress');
var chunk_size = plupload.parseSize(this.getOption('chunk_size'));
if (up.runtime === 'html5' && chunk_size) {
progress.setChunkProgess(chunk_size);
}
},
'UploadProgress': function(up, file) {
var progress = new FileProgress(file, 'fsUploadProgress');
var chunk_size = plupload.parseSize(this.getOption('chunk_size'));
progress.setProgress(file.percent + "%", file.speed, chunk_size);
},
'UploadComplete': function() {
$('#success').show();
},
'FileUploaded': function(up, file, info) {
var progress = new FileProgress(file, 'fsUploadProgress');
progress.setComplete(up, info);
},
'Error': function(up, err, errTip) {
$('table').show();
var progress = new FileProgress(err.file, 'fsUploadProgress');
progress.setError();
progress.setStatus(errTip);
}
}
});
uploader2.bind('FileUploaded', function() {
console.log('hello man 2,a file is uploaded');
});
$('#up_load2').on('click', function(){
uploader2.start();
});
$('#stop_load2').on('click', function(){
uploader2.stop();
});
相应的index.html文件加入相关按钮:
<div id="container">
<a class="btn btn-default btn-lg " id="pickfiles" style="width:160px" href="#" >
<i class="glyphicon glyphicon-plus"></i>
<span>选择文件</span>
</a>
<a class="btn btn-default btn-lg " id="up_load" style="width:160px" href="#" >
<span>确认上传</span>
</a>
<a class="btn btn-default btn-lg " id="stop_load" style="width:160px" href="#" >
<span>暂停上传</span>
</a>
</div>
<div id="container2">
<a class="btn btn-default btn-lg " id="pickfiles2" style="width:160px" href="#" >
<i class="glyphicon glyphicon-plus"></i>
<span>选择文件</span>
</a>
<a class="btn btn-default btn-lg " id="up_load2" style="width:160px" href="#" >
<span>确认上传</span>
</a>
<a class="btn btn-default btn-lg " id="stop_load2" style="width:160px" href="#" >
<span>暂停上传</span>
</a>
</div>
贡献代码
-
登录 https://github.com
-
Fork git@github.com:qiniu/js-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
许可证
Copyright (c) 2017 qiniu.com
基于 MIT 协议发布