cloud-oss

针对云服务器文件上传封装，主要功能：普通上传，分片上传，暂停上传，断点续传，取消上传等（目前就阿里云，后续会扩展华为云，腾讯云等）

使用文档

阿里云

华为云

腾讯云

阿里云

创建存储实例

createCloudOss(cloudType, options)

使用示例

import { createCloudOss } from "cloud-oss";

const cloudOss = await createCloudOss("Aliyun", {
  accessKeyId: uploadInfo.accessKeyId,
  accessKeySecret: uploadInfo.accessKeySecret,
  stsToken: uploadInfo.token,
  bucket: uploadInfo.bucketName,
});

参数

• cloudType: 云服务类型：Aliyun
• options {Object} 配置
  • accessKeyId {String} - 在阿里云控制台网站上创建的 Access Key。
  • accessKeySecret {String} - 创建的 Access Secret。
  • stsToken {String} - 用于临时授权的 Token，详见下文。
  • refreshSTSToken {Function} - 用于在 STS 信息过期时自动设置 stsToken、accessKeyId、accessKeySecret 的回调函数。返回值必须是包含 stsToken、accessKeyId、accessKeySecret 的对象。
  • refreshSTSTokenInterval {Number} - 刷新 STS Token 的时间间隔（毫秒），应该小于 STS 信息过期间隔，默认为 300000 毫秒（5 分钟）。
  • bucket {String} - 默认要访问的存储桶。如果没有存储桶，请首先使用 putBucket()创建一个。
  • endpoint {String} - OSS 区域域名。优先级高于 region。根据不同需求设置为外网域名、内网域名、加速域名等。请参考阿里云 OSS 区域与域名。
  • region {String} - 存储桶数据的区域位置，请参考数据中心，默认为 oss-cn-hangzhou。
  • internal {Boolean} - 是否使用阿里云内部网络访问 OSS，默认为 false。如果您的服务器也在阿里云上运行，可以设置为 true 以节省大量费用。
  • secure {Boolean} - 指示 OSS 客户端使用 HTTPS（secure: true）还是 HTTP（secure: false）协议。
  • timeout {String|Number} - 所有操作的实例级超时时间，默认为 60 秒。
  • cname {Boolean} - 默认为 false，是否使用自定义域名访问 OSS。如果为 true，可以在 endpoint 字段中填写自定义域名。
  • isRequestPay {Boolean} - 默认为 false，是否开启存储桶的请求支付功能。如果为 true，将向 OSS 服务器发送头部 'x-oss-request-payer': 'requester'。详情请参见请求支付。
  • useFetch {Boolean} - 默认为 false，仅在浏览器中有效。如果为 true，表示使用 fetch 模式上传对象，否则使用 XMLHttpRequest。
  • enableProxy {Boolean} - 启用代理请求，默认为 false。
  • proxy {String|Object} - 代理代理 URI 或选项，默认为 null。
  • retryMax {Number} - 在请求错误为网络错误或超时时，自动重试的最大次数。注意：不支持使用流（stream）的 put、putStream 和 append 操作，因为流只能消耗一次。
  • maxSockets {Number} - 允许每个主机的最大套接字数。默认为无限制。

返回值

• cloudOss {Object} - 初始化后实例对象,拿到实例后访问 API

API

cloudOss.signatureUrl(name, options) 获取文件的预览或下载 URL

使用示例

cloudOss.signatureUrl('temp/images/xxx.png').then(res => {
  console.log('获取文件的预览或下载URL：'res)
}).catch(err => {
  console.error('获取失败：'err)
})

参数：

• name {String}：存储在 OSS 上的对象名称。
• options {Object}：可选参数。
  • expires {Number}：过期秒数后，URL 将失效（默认为 1800 秒）。
  • method {String}：HTTP 方法（默认为 'GET'）。
  • Content-Type {String}：设置请求内容类型。
  • process {String}：图像处理参数，将与 x-oss-process 一起发送，例如：{process: 'image/resize,w_200'}。
  • trafficLimit {Number}：流量限制，范围：819200~838860800。
  • subResource {Object}：URL 中的附加签名参数。
  • response {Object}：设置下载的响应头。
  • content-type {String}：设置响应内容类型。
  • content-disposition {String}：设置响应内容 disposition。
  • cache-control {String}：设置响应缓存控制。
  • callback {Object}：设置操作的回调。
    • url {String}：设置回调的 URL。
    • host {String}：设置回调的主机。
    • body {String}：设置回调的主体。
    • contentType {String}：设置主体的类型。
    • customValue {Object}：设置回调的自定义值，例如：{var1: value1, var2: value2}。
  • strictObjectNameValidation {boolean}：严格验证对象名称的标志，默认为 true。

返回值

• res {string} - URL 地址

cloudOss.put(options) 简单上传

使用示例

  const onProgress = ({ percent }) => {
    console.log('当前上传进度：', percent)
  }
  cloudOss.put({
      name,
      file,
      action: 'https://xxx.xxxx.com.cn',
      onProgress,
    }).then((res) => {
      console.log("then:res",res);
    }).catch((err) => {
      console.log("catch:catch", err);
    });

参数

• options {Object} - 配置参数。
  • name {String} - 对象名称，存储在 OSS 上。
  • file {File（仅支持浏览器）| Blob（仅支持浏览器）} 。
  • action {String} - 上传路径，例如：https://xxx.xxxx.com.cn
  • onProgress {Function} - 请求进度回调，会返回{ percent：100 } 进度对象
  • expiration {String} - 过期时间，例如：'2024-01-15T07:14:57.788Z' 默认：一个小时

返回值

• res {Object} - 信息。
  • name {Number} - 对象名称。

cloudOss.multipartUpload(name, file, options) 分片上传

使用示例

const onProgress = ({ percent }) => {
  console.log('当前上传进度：', percent)
}

cloudOss.multipartUpload('temp/video/xxx.mp4', file, {
  onProgress
}).then(res => {
  console.log('上传成功后信息：'res)
}).catch(err => {
  console.error('上传失败：'err)
})

参数

• name {String} - 对象名称
• file {String|File(仅支持浏览器)|Blob(仅支持浏览器)|Buffer} - 文件路径或 HTML5 Web 文件或 Web Blob 或内容缓冲区
• options {Object} - 可选参数
  • parallel {Number} - 并行上传的分片数量 默认：4
  • partSize {Number} - 每个分片的建议大小，默认为 1024 * 4（4MB），最小为 100 _ 1024（100KB）
  • timeout {Number} - 请求超时的毫秒数 默认：120000
  • onProgress {Function} - 请求进度回调，会返回{ percent：100 } 进度对象
  • onCancelComplete {Function} - 暂停成功后回调

返回值

• res {Object} - 响应信息
  • status {Number} - 响应状态码
  • headers {Object} - 响应头信息
  • size {Number} - 响应大小
  • rt {Number} - 请求总耗时（毫秒）
  • bucket {String} - 存储桶名称
  • name {String} - 存储在 OSS 上的对象名称
  • etag {String} - 对象 ETag，包含引号，例如："5B3C1A2E053D763E1B002CC607C5A0FE"
  • data {Object} - 回调服务器响应数据，SDK 使用 JSON.parse()解析后返回

cloudOss.abort() 取消上传(注：取消成功后会走catch)

使用示例

const onProgress = ({ percent }) => {
  console.log('当前上传进度：', percent)
}

cloudOss.multipartUpload('temp/video/xxx.mp4', file, {
  onProgress
}).then(res => {
  console.log('上传成功后信息：'res)
}).catch(err => {
  console.error('上传失败：'err)
})

// 5秒后取消上传
setTimeout(() => {
  cloudOss.abort();
}, 5000)

参数

• 无

返回值

• 无

cloudOss.cancel() 暂停上传(注：分片上传的情况下有效)

使用示例

const onProgress = ({ percent }) => {
  console.log('当前上传进度：', percent)
}

cloudOss.multipartUpload('temp/video/xxx.mp4', file, {
  onProgress
}).then(res => {
  console.log('上传成功后信息：'res)
}).catch(err => {
  console.error('上传失败：'err)
})

// 5秒后暂停上传
setTimeout(() => {
  cloudOss.cancel();
}, 5000)

参数

• 无

返回值

• 无

cloudOss.recovery() 恢复上传(注：分片上传的情况下有效)

使用示例

const onProgress = ({ percent }) => {
  console.log('当前上传进度：', percent)
}

cloudOss.multipartUpload('temp/video/xxx.mp4', file, {
  onProgress
}).then(res => {
  console.log('上传成功后信息：'res)
}).catch(err => {
  console.error('上传失败：'err)
})

// 5秒后暂停上传
setTimeout(() => {
  cloudOss.cancel();
}, 5000)

// 10秒后继续上传
setTimeout(() => {
  cloudOss.recovery();
}, 5000)

参数

• 无

返回值

• 无

华为云

腾讯云