qiniu-js-sdk

基于七牛API及Plupload开发的前端JavaScript SDK

示例网站：七牛JavaScript SDK 示例网站 - 配合七牛nodejs SDK

概述

本SDK适用于IE8+、Chrome、Firefox、Safari 等浏览器，基于七牛云存储官方API 构建，其中上传功能基于 Plupload 插件封装。开发者使用本 SDK 可以方便的从浏览器端上传文件至七牛云存储，并对上传成功后的图片进行丰富的数据处理操作。本 SDK 可使开发者忽略上传底层实现细节，而更多的关注 UI 层的展现。

功能简介

上传
html5模式大于4M时可分块上传，小于4M时直传
Flash、html4模式直接上传
继承了Plupload的功能，可筛选文件上传、拖曳上传等
下载(公开资源)
数据处理（图片）
imageView2（缩略图）
imageMogr2（高级处理，包含缩放、裁剪、旋转等）
imageInfo （获取基本信息）
exif （获取图片EXIF信息）
watermark （文字、图片水印）
pipeline （管道，可对imageView2、imageMogr2、watermark进行链式处理）

SDK构成介绍

Plupload ，建议 2.1.1 及以上版本
qiniu.js，SDK主体文件，上传功能\数据处理实现

安装和运行程序

服务端准备

本SDK依赖服务端颁发upToken，可以通过以下二种方式实现：
- 利用七牛服务端SDK构建后端服务
- 利用七牛底层API构建服务，详见七牛上传策略和上传凭证
后端服务应提供一个URL地址，供SDK初始化使用，前端通过Ajax请求该地址后获得upToken。Ajax请求成功后，服务端应返回如下格式的json：
```
    {
        "uptoken": "0MLvWPnyya1WtPnXFy9KLyGHyFPNdZceomL..."
    }
```
引入Plupload
- Plupload下载，建议 2.1.1 及以上版本
- 引入plupload.full.min.js（产品环境）或引入plupload.dev.js和moxie.js（开发调试）
引入qiniu.js
- 获取SDK源码 git clone [email protected]:qiniupd/qiniu-js-sdk.git，qiniu.js位于src目录内

初始化上传

var uploader = Qiniu.uploader({
    runtimes: 'html5,flash,html4',    //上传模式,依次退化
    browse_button: 'pickfiles',       //上传选择的点选按钮，**必需**
    uptoken_url: '/uptoken',            //Ajax请求upToken的Url，**强烈建议设置**（服务端提供）
    // downtoken_url: '/downtoken',
    // Ajax请求downToken的Url，私有空间时使用,JS-SDK将向该地址POST文件的key和domain,服务端返回的JSON必须包含`url`字段，`url`值为该文件的下载地址
    // uptoken : '<Your upload token>', //若未指定uptoken_url,则必须指定 uptoken ,uptoken由其他程序生成
    // unique_names: true, // 默认 false，key为文件名。若开启该选项，SDK会为每个文件自动生成key（文件名）
    // save_key: true,   // 默认 false。若在服务端生成uptoken的上传策略中指定了 `sava_key`，则开启，SDK在前端将不对key进行任何处理
    domain: 'http://qiniu-plupload.qiniudn.com/',   //bucket 域名，下载资源时用到，**必需**
    get_new_uptoken: false,  //设置上传文件的时候是否每次都重新获取新的token
    container: 'container',           //上传区域DOM ID，默认是browser_button的父元素，
    max_file_size: '100mb',           //最大文件体积限制
    flash_swf_url: 'js/plupload/Moxie.swf',  //引入flash,相对路径
    max_retries: 3,                   //上传失败最大重试次数
    dragdrop: true,                   //开启可拖曳上传
    drop_element: 'container',        //拖曳上传区域元素的ID，拖曳文件或文件夹后可触发上传
    chunk_size: '4mb',                //分块上传时，每片的体积
    auto_start: true,                 //选择文件后自动上传，若关闭需要自己绑定事件触发上传,
    //x_vars : {
    //    自定义变量，参考http://developer.qiniu.com/docs/v6/api/overview/up/response/vars.html
    //    'time' : function(up,file) {
    //        var time = (new Date()).getTime();
              // do something with 'time'
    //        return time;
    //    },
    //    'size' : function(up,file) {
    //        var size = file.size;
              // do something with 'size'
    //        return size;
    //    }
    //},
    init: {
        'FilesAdded': function(up, files) {
            plupload.each(files, function(file) {
                // 文件添加进队列后,处理相关的事情
            });
        },
        'BeforeUpload': function(up, file) {
               // 每个文件上传前,处理相关的事情
        },
        'UploadProgress': function(up, file) {
               // 每个文件上传时,处理相关的事情
        },
        'FileUploaded': function(up, file, info) {
               // 每个文件上传成功后,处理相关的事情
               // 其中 info 是文件上传成功后，服务端返回的json，形式如
               // {
               //    "hash": "Fh8xVqod2MQ1mocfI4S4KpRL6D98",
               //    "key": "gogopher.jpg"
               //  }
               // 参考http://developer.qiniu.com/docs/v6/api/overview/up/response/simple-response.html

               // var domain = up.getOption('domain');
               // var res = parseJSON(info);
               // var sourceLink = domain + res.key; 获取上传成功后的文件的Url
        },
        'Error': function(up, err, errTip) {
               //上传出错时,处理相关的事情
        },
        'UploadComplete': function() {
               //队列文件处理完毕后,处理相关的事情
        },
        'Key': function(up, file) {
            // 若想在前端对每个文件的key进行个性化处理，可以配置该函数
            // 该配置必须要在 unique_names: false , save_key: false 时才生效

            var key = "";
            // do something with key here
            return key
        }
    }
});

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

// uploader 为一个plupload对象，继承了所有plupload的方法，参考http://plupload.com/docs

如果一个页面中有多个上传实例，可以如下操作

var option1 = {
    key : val ,
    ……
};
var uploader = Qiniu.uploader(option1);

var Qiniu2 = new QiniuJsSDK();
var option2 = {
    key : val ,
    ……
};
var uploader2 = Qiniu2.uploader(option2);

运行网站，通过点击pickfiles元素，选择文件后上传

对上传成功的图片进行数据处理

watermark（水印）

    // key 为每个文件上传成功后，服务端返回的json字段，即资源的最终名字，下同
    // key 可在每个文件'FileUploaded'事件被触发时获得

    var imgLink = Qiniu.watermark({
         mode: 1,  // 图片水印
         image: 'http://www.b1.qiniudn.com/images/logo-2.png', // 图片水印的Url，mode = 1 时 **必需**
         dissolve: 50,          // 透明度，取值范围1-100，非必需，下同
         gravity: 'SouthWest',  // 水印位置，为以下参数[NorthWest、North、NorthEast、West、Center、East、SouthWest、South、SouthEast]之一
         dx: 100,  // 横轴边距，单位:像素(px)
         dy: 100   // 纵轴边距，单位:像素(px)
     }, key);      // key 为非必需参数，下同

    // imgLink 可以赋值给 html 的 img 元素的 src 属性，下同

    // 若未指定key，可以通过以下方式获得完整的 imgLink，下同
    // imgLink  =  '<domain>/<key>?' +  imgLink
    // <domain> 为七牛空间（bucket)对应的域名，选择某个空间后，可通过"空间设置->基本设置->域名设置"查看获取

或

    var imgLink = Qiniu.watermark({
         mode: 2,  // 文字水印
         text: 'hello world !', // 水印文字，mode = 2 时 **必需**
         dissolve: 50,          // 透明度，取值范围1-100，非必需，下同
         gravity: 'SouthWest',  // 水印位置，同上
         fontsize: 500,         // 字体大小，单位: 缇
         font : '黑体',          // 水印文字字体
         dx: 100,  // 横轴边距，单位:像素(px)
         dy: 100,  // 纵轴边距，单位:像素(px)
         fill: '#FFF000'        // 水印文字颜色，RGB格式，可以是颜色名称
     }, key);

具体水印参数解释见水印（watermark）

imageView2

    var imgLink = Qiniu.imageView2({
       mode: 3,  // 缩略模式，共6种[0-5]
       w: 100,   // 具体含义由缩略模式决定
       h: 100,   // 具体含义由缩略模式决定
       q: 100,   // 新图的图像质量，取值范围：1-100
       format: 'png'  // 新图的输出格式，取值范围：jpg，gif，png，webp等
     }, key);

具体缩略参数解释见图片处理（imageView2）

imageMogr2

    var imgLink = Qiniu.imageMogr2({
       auto-orient: true,  // 布尔值，是否根据原图EXIF信息自动旋正，便于后续处理，建议放在首位。
       strip: true,   // 布尔值，是否去除图片中的元信息
       thumbnail: '1000x1000'   // 缩放操作参数
       crop: '!300x400a10a10',  // 裁剪操作参数
       gravity: 'NorthWest',    // 裁剪锚点参数
       quality: 40,  // 图片质量，取值范围1-100
       rotate: 20,   // 旋转角度，取值范围1-360，缺省为不旋转。
       format: 'png',// 新图的输出格式，取值范围：jpg，gif，png，webp等
       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', // 指定watermark操作
        mode: 2, // 此参数同watermark函数的参数，下同。
        text: 'hello world !',
        dissolve: 50,
        gravity: 'SouthWest',
        fontsize: 500,
        font : '黑体',
        dx: 100,
        dy: 100,
        fill: '#FFF000'
    },{
        fop: 'imageView2',  // 指定imageView2操作
        mode: 3,  // 此参数同imageView2函数的参数，下同
        w: 100,
        h: 100,
        q: 100,
        format: 'png'
    },{
        fop: 'imageMogr2',  // 指定imageMogr2操作
        auto-orient: true,  // 此参数同imageMogr2函数的参数，下同。
        strip: true,
        thumbnail: '1000x1000'
        crop: '!300x400a10a10',
        gravity: 'NorthWest',
        quality: 40,
        rotate: 20,
        format: 'png',
        blur:'3x5'
    }];

    // fopArr 可以为三种类型'watermark'、'imageMogr2'、'imageView2'中的任意1-3个
    // 例如只对'watermark'、'imageMogr2'进行管道操作，则如下即可
    // var fopArr = [{
    //    fop: 'watermark', // 指定watermark操作
    //    mode: 2, // 此参数同watermark函数的参数，下同。
    //    text: 'hello world !',
    //    dissolve: 50,
    //     gravity: 'SouthWest',
    //     fontsize: 500,
    //     font : '黑体',
    //     dx: 100,
    //     dy: 100,
    //     fill: '#FFF000'
    // },{
    //    fop: 'imageMogr2',  // 指定imageMogr2操作
    //    auto-orient: true,  // 此参数同imageMogr2函数的参数，下同。
    //    strip: true,
    //    thumbnail: '1000x1000'
    //    crop: '!300x400a10a10',
    //    gravity: 'NorthWest',
    //    quality: 40,
    //    rotate: 20,
    //    format: 'png',
    //    blur:'3x5'
    // }];


    var imgLink = Qiniu.pipeline(fopArr, key));

具体管道操作解释见管道操作

运行示例

直接运行本SDK示例网站的服务

安装 Nodejs、npm
获取源代码： git clone [email protected]:qiniupd/qiniu-js-sdk.git

进入demo目录,修改config.js，Access Key和Secret Key 按如下方式获取

开通七牛开发者帐号

登录七牛开发者自助平台，查看 AccessKey 和 SecretKey 。

    module.exports = {
        'ACCESS_KEY': '<Your Access Key>',
        'SECRET_KEY': '<Your Secret Key>',
        'Bucket_Name': '<Your Bucket Name>',
        'Port': 18080,
        'Uptoken_Url': '<Your Uptoken_Url>',
        'Domain': '<Your Bucket Domain>'
    }

在根目录运行make启动
访问http://127.0.0.1:18080/或http://localhost:18080/

说明

本SDK依赖Plupload，初始化之前请引入Plupload。
本SDK依赖uptoken，可以通过提供Ajax请求地址 uptoken_url 或者直接设置 uptoken 实现，强烈建议前者。
如果您想了解更多七牛的上传策略，建议您仔细阅读七牛官方文档-上传。另外，七牛的上传策略是在后端服务指定的，本SDK的 setOption API 只是设置 Plupload的初始化参数，和上传策略无关。
如果您想了解更多七牛的图片处理，建议您仔细阅读七牛官方文档-图片处理
如果是 https 网站，上传地址为 https://up.qbox.me 否则使用 http://upload.qiniu.com
本SDK示例生成upToken时，指定的Bucket Name为公开空间，所以可以公开访问上传成功后的资源。若您生成upToken时，指定的Bucket Name为私有空间，那您还需要在服务端进行额外的处理才能访问您上传的资源。具体参见下载凭证。本SDK数据处理部分功能不适用于私有空间。

贡献代码

登录 https://github.com
Fork [email protected]:qiniupd/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) 2014 qiniu.com

基于 GPL V2 协议发布:

www.gnu.org/licenses/gpl-2.0.html

evolink / js-sdk Goto Github PK

js-sdk's Introduction

qiniu-js-sdk

概述

功能简介

SDK构成介绍

安装和运行程序

运行示例

说明

贡献代码

许可证

基于 GPL V2 协议发布:

js-sdk's People

Contributors

Watchers

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent