@pluve/storage-client

@pluve/storage-client 基于 XMLHttpRequest 实现，封装了文件上传，图片旋转、压缩功能。当前版本仅支持上传文件到 OSS(阿里云)/OBS(华为云)，兼容低版本浏览器。其中图片旋转功能依赖exif-ts .

version: 1.0.0
npm: @pluve/storage-client
date: 2021/03/05

安装

npm i -S @pluve/storage-client

使用

import { StorageClient } from '@pluve/storage-client';

StorageClient 使用说明

StorageClient 主要用于文件上传，包含接口如下

接口	参数	说明
config	IStorageConfig	配置文件上传工具
getSignature	ISignatureRequest	获取文件上传签名
upload	IUpload	直接上传文件，省略getSignature步骤
uploadBySignature	IUploadBySignature	通过文件上传签名上传文件，需先通过getSignature获取文件上传签名

StorageClient 相关类型说明

IStorageConfig 类型说明

配置 StorageClient

interface StorageClient {
  signatureHost: string; // 文件签名获取域名
  signaturePath: string; // 文件签名获取接口地址
  debug?: boolean; // 是否开启debug模式，默认关闭
  timeout?: number; // 文件上传超时时间
}

ISignatureRequest 类型说明

获取文件签名时参数

interface ISignatureData {
  key: string;
  mimeType?: FileMediaType;
  successActionStatus?: string;
}

interface ISignatureRequest {
  data: ISignatureData; // 获取文件上传签名参数
  headers?: Headers; // 获取文件上传签名请求头
  storageConfig?: IStorageConfig; // FileAgent配置信息
}

ISignatureResp 类型说明

对象存储服务签名数据结构。目前支持阿里云和华为云

interface ISignatureResp {
  key: string; // 文件唯一标志
  policy: string; // policy
  signature: string; // 签名
  host: string; // 文件存储服务域名
  expire: string; // 失效时间
  accessKey: string; // AccessID
  storageType: StorageType; // 存储服务类型
}

/**
 * OSS签名信息
 */
interface IOSSSignatureResp extends ISignatureResp {
  accessID: string;
}

/**
 * OBS签名
 */
interface IOBSSignatureResp extends ISignatureResp {
  mimeType: string; // 文件类型
  stsToken: string; // token
  successActionStatus?: string; // 成功状态码
}

// 注意，host + '/' + key 即为文件的网络地址
const fileUrl = `${host}/${key}`;

IUpload

直接上传文件参数

enum FileMediaType {
  TEXT = 'text/plain', // 文本
  IMAGE_JPEG = 'image/jpeg', // 图片
  IMAGE_PNG = 'image/png', // 图片
  IMAGE_GIF = 'image/gif', // 图片
}

export interface ISignatureData {
  key: string; // 文件名，支持以"/"标记目录
  mimeType?: FileMediaType; // 文件媒体类型
  successActionStatus?: string; // 上传成功响应码
}

interface IUpload {
  file: File | Blob; // 文件
  fileType: FileType; // 文件类型, IMG/OTHER。若文件类型为IMG时，可开启图片旋转和压缩功能
  data: any; // 获取文件上传签名参数
  headers?: Headers; // 获取文件上传签名请求头
  storageConfig?: IStorageConfig; // StorageClient配置信息
  onResult?: (result: IUploadResult) => void; // 文件上传结果回调
  onProgress?: (event: IUploadProgress) => void; // 文件上传进度回调
  compress?: boolean; // 是否开启文件压缩，在fileType值为IMG时有效
  rotateImage?: boolean; // 是否开题文件旋转，在fileType值为IMG时有效
}

IUploadBySignature

通过文件上传签名来上传文件

interface IUploadBySignature {
  file: File | Blob; // 文件
  fileType: FileType; // 文件类型, IMG/OTHER。若文件类型为IMG时，可开启图片旋转和压缩功能
  signatureData: ISignature; // 签名数据
  onResult?: (result: IUploadResult) => void; // 文件上传结果回调
  onProgress?: (event: IUploadProgress) => void; // 文件上传进度回调
  compress?: boolean; // 是否开启文件压缩，在fileType值为IMG时有效
  rotateImage?: boolean; // 是否开题文件旋转，在fileType值为IMG时有效
}

IUploadProgress

文件上传进度信息

interface IUploadProgress {
  total: string; // 文件大小
  speed: string; // 文件传输速率
  restTime: string; // 预估剩余上传时间
  percent: string; // 上传进度
}

IUploadResult

文件上传结果

interface IUploadResult {
  success: boolean; // 是否上传成功
  canceled: boolean; // 是否取消上传
  url?: string; // 上传成功后有值，为文件网络地址
}

使用示例

@pluve/storage-client 目前可在 react/react-native/vue 项目中使用。在小程序中，请使用wx.uploadFile API。

代码示例

import { StorageClient } from '@pluve/storage-client';

// 获取FileAgent对象
const storageClient = StorageClient.getInstance();

// 配置FileAgent，可选。可使用该接口进行一次性配置
const storageConfig = {
  signatureHost: 'https://xxx.com', // 文件签名获取域名
  signaturePath: '/signature', // 文件签名获取接口地址
  debug: true, // 是否开启debug模式，默认关闭
  timeout: 15000, // 上传文件超时时间为15秒
};
storageClient.config(storageConfig);

// 同步方式获取文件上传签名信息
const signatureData = storageClient.getSignature({
  data: {
    key: 'fileName.sufix', // 文件名称
  },
  headers: undefined, // 请求头
  storageConfig: undefined, // 已在前面配置过，所以此处可以省略。
});

// 直接上传文件，不关注文件签名等细节
storageClient.upload({
  file, // 文件
  fileType: 'IMG',
  data: {
    key: 'fileName.sufix', // 文件名称
  },
  headers: undefined,
  storageConfig,
  onResult: (result: IUploadResult) => {
    // 处理文件上传结果
  },
  onProgress: (event: IUploadProgress) => {
    // 展示文件上传进度信息
  },
  compress: true, // 是否开启文件压缩，在fileType值为IMG时有效
  rotateImage: true, // 是否开题文件旋转，在fileType值为IMG时有效
});

storageClient.uploadBySignature({
  file,
  fileType: 'IMG',
  signatureData,
  onResult: (result: IUploadResult) => {
    // 处理文件上传结果
  },
  onProgress: (event: IUploadProgress) => {
    // 展示文件上传进度信息
  },
  compress: true, // 是否开启文件压缩，在fileType值为IMG时有效
  rotateImage: true, // 是否开题文件旋转，在fileType值为IMG时有效
});

微信中上传文件到 云存储 参考示例.

const { host, accessID, expire, key, policy, signature } = signatureData;
const dataContent = {
  OSSAccessKeyId: accessID,
  policy: policy,
  signature: signature,
  key: key,
  expire: expire,
  excel_url: host + '/' + key,
  success_action_status: '200',
};
wx.uploadFile({
  url: host,
  filePath,
  name: 'file',
  formData: dataContent, // 请求额外的form data
  success: () => {
    if (onResult) {
      onResult({ success: true, url: host + '/' + key });
    }
  },
  fail: () => {
    if (onResult) {
      onResult({ success: false, url: null, message: '文件上传失败' });
    }
  },
});

外部依赖

依赖 EXIF 插件，用于自动旋转图片

issues 说明

暂无版本计划

TODO

未来计划支持的云存储服务

云储存服务	说明	说明
COS	腾讯云
S3	亚马逊
QINIU	七牛