Skip to content

zhang0ZGC/alioss-web-uploader

Repository files navigation

alioss-web-uploader

NPM version min size min+gzip size

在浏览器端直传文件到阿里 OSS

[在线 DEMO]1

兼容性

理论上支持 FormData API 的浏览器都可以(IE 10+)。详细兼容性见: https://caniuse.com/#feat=mdn-api_formdata

更多浏览器支持可参阅相关官方文档提供的方案: JavaScript客户端签名直传

安装

使用 yarn 或 npm 安装

yarn add alioss-web-uploader
npm install alioss-web-uploader

浏览器直接引入

在浏览器使用 script 标签直接引入 js 文件, 并使用全局变量 AliOSSWebUploader

发布包内 dist 目录提供了 alioss-web-uploader.jsalioss-web-uploader.min.js

或者使用公共 CDN:

alioss-web-uploader

https://cdn.jsdelivr.net/npm/alioss-web-uploader/dist/alioss-web-uploader.min.js

UNPKG

https://unpkg.com/alioss-web-uploader/dist/alioss-web-uploader.min.js

使用

oss(options)

options

  • accessKeyId {String}
  • accessKeySecret {String}
  • [bucket]? {String} Bucket 名称,选择性必填,必须与 region 同时指定。
  • [region]? {String} 地域,默认 oss-cn-hangzhou , 详情 Data Regions
  • [endpoint]? {String} 与bucket绑定的自定义域名,如果指定则忽略 bucketregion 设置,前面不加 http(s)://
  • [stsToken] {String} used by temporary authorization, 强烈建议使用此参数, 查看详情
  • [secure] {Boolean} default undefined. 默认会根据 location.protocol 自动选择是否使用 https 。一般不需要设置,除非需要在 http 页面中使用 https 上传。 注意:不要在 HTTPS 页面中设置为 false(设置了也没用,不可以在 https 页面中使用 http)
  • [timeout] {Number} 请求超时时间,默认 300_000 ( 300 s )

参数详情查看 配置项.

const oss = require('alioss-web-uploader');

// or `const client = oss({...})`
const client = new oss({
    region:'oss-cn-shanghai',
    bucket:'your bucket',
    accessKeyId:'your keyId',
    accessKeySecret: 'your accessKeySecret',
});

.postObject(name, file[, options])

通过postObject接口添加object

参数: object

  • name {string} 对象名称
  • file {File|Blob} 上传的 Blob 或 html5 File
  • [options] {Object} 可选参数
    • [onProgress] {Function} 上传进度回调。(IE 系列因不支持 xhr.upload 属性,所以回调不会被执行)
    • [onSuccess] {Function} 成功回调
    • [onError] {Function} 错误回调
    • [onAbort] {Function} 中断上传回调
    • [timeout] {Number} 超时时间,单位 ms, 默认 client.opts.timeout 300s
    • [policy] {Object|String} [policy 对象]2或 json 字符串的 base64
    • [signature] {String} policyBase64 签名,通常不需要传,因为会自动计算签名
    • [x-oss-object-acl] {String} 指定 OSS 创建 Object 时的访问权限。合法值:public-read、private、public-read-write
    • [x-oss-meta-*] 用户指定的 user meta 值。
    • [x-oss-*]
    • 更多参数
    • [headers] {Object} object header 信息,用以指定下载时的 headers,详情见 [RFC2616]3 ([中文]4)
      • 'Cache-Control' cache control for download, e.g.: Cache-Control: public, no-cache
      • 'Content-Disposition' object name for download, e.g.: Content-Disposition: somename
      • 'Content-Encoding' object content encoding for download, e.g.: Content-Encoding: gzip
      • 'Expires' expires time (milliseconds) for download, e.g.: Expires: 3600000

返回: object

  • abort {Function} 可用于中断上传
const blob = new Blob(['hello world'], {type: 'text/plain'});
const options = {
    'x-oss-object-acl': 'public-read',
    onProgress: e=>console.log(`complete ${e.percent.toFixed(2)}%`),
    onSuccess: () => console.log('upload success'),
    onError: (e) => console.warn(e),
};
const uploader = client.postObject('hello/world.txt', blob, options);
// uploader.abort()

在浏览器中直接使用example 文件夹或查看 [在线 demo]1

.generateObjectUrl(name[, baseUrl])

获取对象 url,如果 object 设置的 ACL 权限为 public-readpublic-read-write,可通过此 url 直接下载文件。

参数:

  • name {String} 对象名称
  • [baseUrl] {String} 如果提供 baseUrl, 将会使用 baseUrl 代替默认的 bucketendpoint
client.generateObjectUrl('hello/world.txt');
// => http(s)://${bucket}.${region}.aliyuncs.com/hello/world.txt
// => http(s)://${endpoint}/hello/world.txt (if endpoint is provided )

client.generateObjectUrl('hello/world.txt', 'http://mycdn.domain.com');
// => http://mycdn.domain.com/hello/world.txt

参考

TODO(maybe)

  • signatureUrl
  • putObject
  • iframe upload

Footnotes

  1. https://unpkg.com/alioss-web-uploader/example/index.html 2

  2. https://help.aliyun.com/document_detail/31988.html#title-5go-s2f-dnw

  3. http://www.w3.org/Protocols/rfc2616/rfc2616.html

  4. https://www.cnblogs.com/k1988/archive/2010/01/12/2165683.html