@aplus-frontend/oss

快速开始

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

使用示例

`javascript
//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)
`

方法说明

$3

类型: initOssClient(options: RequestOssOptions): Promise

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

RequestOssOptions

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

$3

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

说明: 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 | 上传路径前缀拼接 |
| bucketConfig | RequestOssOptions | - | （可选）临时桶配置，用于单次上传到指定桶 |
| widthCallBackParams | widthCallBackParams | Record | （可选）自定义回调callBack携带的参数 |

> (OSS支持在文件上传后自动触发回调，通知应用服务器执行后续操作)[https://www.alibabacloud.com/help/zh/oss/developer-reference/callback#51f72e9498gas]

`javascript
const onFileChange = async (e) => {
let res = await client.put({
fileName: file.name,
fileType: file.type,
dirName: 'UPLOAD_TEST',
data: file,
progressCallBack: (progress: number) => {
console.log(Upload progress: ${progress}%);
},
needHash: false,
widthCallBackParams: {
userCode: '12345',
fileExplanation: 'test file',
client: 'quick-bi'
}
});
console.log(res)
};

`

$3

类型: extractZip(file: File): Promise;

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

extractZip 参数说明

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

$3

`javascript

//上传 zip 文件示例

//模板


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

$3

类型: downloadFile(savePathName: Array | string | Array<{path: string;fileName: string;}>, bucketConfig?: RequestOssOptions): Promise

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

downloadFile 参数说明

| 参数 | 类型 | 默认值 | 说明 |
| ------------ | -------------------------------------------------------------------- | ------ | ---------------------------------------- |
| savePathName | Array \| string \| Array<{path: string;fileName: string;}> | - | 多文件下载为数组，单文件下载为字符串 |
| bucketConfig | RequestOssOptions | - | （可选）临时桶配置，用于从指定桶下载文件 |

$3

类型: getSignatureUrl(name: string, expires?: number, rename?: string, disposition?: 'inline' | 'attachment', bucketConfig?: RequestOssOptions): Promise;

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

getSignatureUrl 参数说明

| 参数 | 类型 | 默认值 | 说明 |
| ------------ | -------------------------- | -------- | ---------------------------------------------- |
| name | string | - | 文件路径名 |
| expires | number | 3600(秒) | 过期时间 |
| rename | string | - | 自定义文件名 |
| disposition | 'inline' \| 'attachment' | - | 预览模式：inline-在线预览，attachment-附件下载 |
| bucketConfig | RequestOssOptions | - | （可选）临时桶配置，用于从指定桶获取签名URL |

$3

类型: getOssFileSize(name: string, bucketConfig?: RequestOssOptions): Promise;

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

getOssFileSize 参数说明

| 参数 | 类型 | 默认值 | 说明 |
| ------------ | ------------------- | ------ | -------------------------------------------- |
| name | string | - | 文件路径名 |
| bucketConfig | RequestOssOptions | - | （可选）临时桶配置，用于从指定桶获取文件大小 |

$3

类型: deleteFile(savePathName: string, isRealDelete?: boolean, bucketConfig?: RequestOssOptions): Promise;

说明: 删除 oss 文件

deleteFile 参数说明

| 参数 | 类型 | 默认值 | 说明 |
| ------------ | ------------------- | ------- | ------------------------------------------------------------------ |
| savePathName | string | - | 文件路径名 |
| isRealDelete | boolean | false | 为避免误删，删除时需手动设置 isRealDelete=true，默认不真正删除文件 |
| bucketConfig | RequestOssOptions | - | （可选）临时桶配置，用于从指定桶删除文件 |

$3

类型: pauseUpload(): Promise;

说明: 暂停上传

$3

类型: switchBucket(bucketConfig: RequestOssOptions): Promise;

说明: 切换或初始化新的 OSS 桶，适用于需要长期使用某个桶进行多次操作的场景

switchBucket 参数说明

| 参数 | 类型 | 默认值 | 说明 |
| ------------ | ------------------- | ------ | ---------------------------------------- |
| bucketConfig | RequestOssOptions | - | 桶配置对象，包含 getOssAccess 等配置信息 |

返回值说明

- 返回 true 表示切换成功
- 返回 false 表示切换失败

使用示例

`javascript
// 初始化默认桶
await client.initOssClient({
getOssAccess: () => getOssAccess('default-bucket'),
bucketName: 'default-bucket',
})

// 切换到另一个桶
const success = await client.switchBucket({
getOssAccess: () => getOssAccess('another-bucket'),
})

if (success) {
console.log('切换桶成功')
// 后续操作将使用新桶
await client.put({
fileName: 'test.jpg',
dirName: 'images',
data: file,
progressCallBack: p => console.log(p),
})
}
//之后的后续操作都会是新的桶
`

$3

类型: getCurrentBucketName(): string;

说明: 获取当前使用的桶名称

使用示例

`javascript
const currentBucket = client.getCurrentBucketName()
console.log(当前使用的桶: ${currentBucket})
`

$3

类型: clearBucketCache(bucketName?: string): void;

说明: 清除指定桶的缓存，如果不传参数则清除所有桶的缓存

clearBucketCache 参数说明

| 参数 | 类型 | 默认值 | 说明 |
| ---------- | -------- | ------ | -------------------------------------- |
| bucketName | string | - | （可选）要清除的桶名称，不传则清除所有 |

使用示例

`javascript
// 清除指定桶的缓存
client.clearBucketCache('temp')

// 清除所有桶的缓存
client.clearBucketCache()
`

$3

类型: destroy(): Promise

说明: 销毁 oss 实例

$3

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

$3

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

`javascript
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();
}


`

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

`javascript

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

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

$3

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

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

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

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

`

多桶切换功能

$3

当项目需要在不同的阿里云 OSS 桶之间进行上传和下载操作时，可以通过以下两种方式实现：

#### 方式一：全局切换桶（switchBucket）

适用于需要长期使用某个桶进行多次操作的场景。

`javascript
import { client } from '@aplus-frontend/oss';

// 1. 初始化默认桶
await client.initOssClient({
getOssAccess: () => getOssAccess('default-bucket'),
bucketName: 'default-bucket'
});

// 2. 切换到另一个桶
await client.switchBucket({
getOssAccess: () => getOssAccess('another-bucket'),
});

// 3. 后续操作将使用新桶
await client.put({...});
`

#### 方式二：单次操作使用临时桶配置（bucketConfig）

适用于一次性使用其他桶的场景，系统会自动缓存桶实例。

上传文件到临时桶：

`javascript
await client.put({
fileName: 'test.jpg',
dirName: 'images',
data: file,
bucketConfig: {
getOssAccess: () => getOssAccess('temp-bucket'),
},
progressCallBack: p => console.log(p),
})
`

从临时桶下载文件：

`javascript
await client.downloadFile('images/test.jpg', {
getOssAccess: () => getOssAccess('temp-bucket'),
})
`

从临时桶获取签名URL：

`javascript
const url = await client.getSignatureUrl(
'images/test.jpg',
3600,
'custom-name.jpg',
'attachment',
{
getOssAccess: () => getOssAccess('temp-bucket'),
},
)
`

$3

以下是一个完整的 Vue3 项目示例，展示如何在不同桶之间切换：

`javascript



`

$3

`javascript
// 获取当前使用的桶名称
const currentBucket = client.getCurrentBucketName()
console.log(当前使用的桶: ${currentBucket})

// 清除指定桶的缓存
client.clearBucketCache('temp')

// 清除所有桶的缓存
client.clearBucketCache()
`

$3

1. bucketName 标识：建议为每个桶配置设置唯一的 bucketName，用于缓存管理
2. 自动缓存：使用 bucketConfig 的桶会自动缓存，后续可直接通过 bucketName` 复用
3. 线程安全：单次操作完成后会自动恢复原始客户端实例，不影响其他操作
4. 错误处理：如果桶配置错误或认证失败，操作会返回错误信息