@aplus-frontend/oss

@aplus-frontend/oss

对 ali-oss sdk 进行二次封装，简化阿里云 OSS 文件上传流程

快速开始

//add -w in you root folder
pnpm install @aplus-frontend/oss -S -w

使用示例

//register client instance
import { client } from '@aplus-frontend/oss'

//项目中引入你的 STS 服务
import { you_STS_server } from '@/api/sts'

//初始化 oss 访问令牌
const ossIntsance = await client.initOssClient({
  you_STS_server,
  onFailure: err => {
    console.warn('获取 oss accessSecret 失败', err)
  }
})

//初始化后
//你可以使用 ossIntsance 进行如下操作

ossIntsance.put(..)
ossIntsance.getSignatureUrl(..)
ossIntsance.downloadFile(..)
ossIntsance.deleteFile(..)
ossIntsance.pauseUpload(...)


// 上传图片或视频
// 可通过 put 方法上传
const result = await client.put({
  fileName: file.name,
  dirName: 'video',
  data: file,
  progressCallBack: (p: number) => {
    percentVideo.value = p
  },
  //并发上传分片数
  parallel: 6,
  //每个分片建议大小，默认 1024 * 1024(1MB)，最小 100 * 1024(100KB)
  partSize: 1024 * 1024
})

if (result.status === 200) {
  const { status, previewUrl, saveUrl } = result
  console.log('status---', status)
  console.log('previewUrl---', previewUrl)
  console.log('saveUrl---', saveUrl)
} else {
  //失败
  console.log(result.message)
}

//下载文件
let res = client.downloadFile(fileName)
console.log(res.message)
console.log(res.status)
//获取签名 url 预览
let signatureUrl = client.getSignatureUrl(pathName)
//获取签名 url
//expires 秒后 url 失效，默认 3600s
console.log(signatureUrl)

//删除文件
let res = await client.deleteFile(pathName)
console.log(res)

//暂停上传
let res = await client.pauseUpload()
console.log(res)

方法说明

initOssClient

类型: initOssClient(options: RequestOssOptions): Promise<Oss | null>

说明: 通过你的 sts 服务注册 client 实例

ResquestOssOptions

参数	类型	默认值	说明
getOssAccess	() => Promise<accessCreate>	-	初始化 oss 访问令牌
onFailure	(err: any) => void	-	获取 oss accessSecret 失败回调
locale	zh_CN | en_US	zh_CN	语言
bucket	string	-	（非必填）指定上传的阿里云 bucket

put

类型: put({ fileName, dirName, data, progressCallBack, parallel, partSize }: uploadParams): Promise<actionResponse>;

说明: put 方法可上传图片、视频等文件

put 参数说明

参数	类型	默认值	说明
fileName	string	-	文件名
dirName	string	-	上传文件夹名
data	File	-	上传的数据
progressCallBack	(p:number) => void	-	上传进度回调
parallel	number	6	并发上传分片数
partSize	number	1024*1024(1M)	每个分片建议大小，默认 1MB，最小 100KB
expires	number	1800	url 过期时间（秒），默认 1800
needHash	boolean	true	是否对上传文件名进行 hash
baseDirName	string	Frontend-Upload	上传路径前缀拼接

extractZip

类型: extractZip(file: File): Promise<extractedFile[]>;

说明: 通过 extractZip 方法解压 zip 文件，之后可通过 put 方法逐个上传到阿里云 OSS

extractZip 参数说明

参数	类型	默认值	说明
file	File	-	文件数据

zip 文件上传示例

//上传 zip 文件示例

//模板
 <input type="file" @change="onFileChange" />

//逻辑
 const onFileChange = async (e) => {
      let res = await client.extractZip(e.target.files[0]);
      console.log(res)
  };

downloadFile

类型: downloadFile(savePathName: Array<string> | string | Array<{path: string;fileName: string;}>): Promise<actionResponse>

说明: 通过 downloadFile 方法下载文件（支持多文件下载）

downloadFile 参数说明

参数	类型	默认值	说明
savePathName	Array<string> | string | Array<{path: string;fileName: string;}>	-	多文件下载为数组，单文件下载为字符串

getSignatureUrl

类型: getSignatureUrl(name: string, expires?: number, rename?: string): Promise<string | undefined>;

说明: 获取签名 url 进行预览

getSignatureUrl 参数说明

参数	类型	默认值	说明
name	string	-	文件路径名
expires	number	3600(秒)	过期时间
rename	string	-	自定义文件名

getOssFileSize

类型: getOssFileSize(name: string): Promise<number>;

说明: 获取阿里云 oss 文件大小（单位：MB）

getOssFileSize 参数说明

参数	类型	默认值	说明
name	string	-	文件路径名

deleteFile

类型: deleteFile(savePathName: string, isRealDelete?: boolean): Promise<actionResponse>;

说明: 删除 oss 文件

deleteFile 参数说明

参数	类型	默认值	说明
savePathName	string	-	文件路径名
isRealDelete	boolean	false	为避免误删，删除时需手动设置 isRealDelete=true，默认不真正删除文件

pauseUpload

类型: pauseUpload(): Promise<actionResponse>;

说明: 暂停上传

destroy

类型: destroy(): Promise<actionResponse>

说明: 销毁 oss 实例

actionResponse

参数	类型	默认值	说明
status	number	-	状态码（200 成功，其他为失败）
previewUrl	string	-	上传后可预览图片或视频的 url
saveUrl	string	-	后端保存的路径
message	string	-	成功或失败信息
originalFileName	string	-	上传文件原始名称

Vue3 项目中使用

你可以像下面这样编写全局 Hooks useOss.ts

import { client } from '@aplus-frontend/oss';
import type { Oss } from '@aplus-frontend/oss';
import { getOssAccess } from '@/api/sys/uploadOss';
import { onMounted } from 'vue';
import { useMessage } from '@/hooks/web/useMessage';
const { createMessage } = useMessage();
let ossInstance: Oss;
// 获取 client 实例对象
export function useOss() {
  return {
    client: ossInstance
  };
}
// 初始化 client 实例对象
export function useOssInit() {
  onMounted(async () => {
    ossInstance = await client.initOssClient({
      getOssAccess,
      onFailure: (err) => {
        console.log(err)
      }
    });
  });
  return useOss();
}

在你的应用中需要上传或下载功能时可这样使用：

  import { useOssInit, useOss } from '@/hooks/web/useOss';
  //oss 未初始化时
  //可通过 useOssInit 初始化
  useOssInit();
  //初始化后可通过 useOss 获取 client 实例
  const { client } = useOss();

  const result = await client.put(...)

支持多实例分片上传

通过导出的 createOssInstance 方法可创建多实例分片上传

import { createOssInstance } from '@aplus-frontend/oss';

const client1 = createOssInstance()
client1.put(...)

const client2 = createOssInstance()
client2.put(...)
//暂停 client1 上传
client1.pauseUpload()
//暂停 client2 上传
client2.pauseUpload()