@aplus-frontend/oss

v2.0.4

Published

9 days ago

Rebuild ali-oss javascript sdk that provide private sts server methods

0High
0Medium
0Low

@aplus-frontend @aplus-frontend/oss ollieLiu

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

NPM Version NPM Downloads NPM License

快速开始

//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 实例

RequestOssOptions

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

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

  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)
  };

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;}>, bucketConfig?: RequestOssOptions): Promise<actionResponse>

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

downloadFile 参数说明

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

getSignatureUrl

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

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

getSignatureUrl 参数说明

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

getOssFileSize

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

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

getOssFileSize 参数说明

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

deleteFile

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

说明: 删除 oss 文件

deleteFile 参数说明

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

pauseUpload

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

说明: 暂停上传

switchBucket

类型: switchBucket(bucketConfig: RequestOssOptions): Promise<boolean>;

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

switchBucket 参数说明

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

返回值说明

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

使用示例

// 初始化默认桶
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),
  })
}
//之后的后续操作都会是新的桶

getCurrentBucketName

类型: getCurrentBucketName(): string;

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

使用示例

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

clearBucketCache

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

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

clearBucketCache 参数说明

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

使用示例

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

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

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()

多桶切换功能

功能说明

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

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

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

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）

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

上传文件到临时桶：

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

从临时桶下载文件：

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

从临时桶获取签名URL：

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

实际项目用例

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

<script lang="ts" setup>
import { getOssAccess } from '@/api'
import { client, Oss } from '@aplus-frontend/oss'
import { onMounted, ref } from 'vue'
const oss = ref<Oss>()

// 根据桶名称获取对应的获取accessSecret方法和失败回调
const getBucketOptionsByName = (bucketName: string = 'front-ljh') => {
  switch (bucketName) {
    case 'front-ljh':
      return {
        getOssAccess: () => getOssAccess('front-ljh'),
        onFailure: (err: any) => {
          console.warn('获取 oss front-ljh 桶accessSecret 失败', err)
        },
      }
    case 'elnkproqa':
      return {
        getOssAccess: () => getOssAccess('elnkproqa'),
        onFailure: (err: any) => {
          console.warn('获取 oss elnkproqa桶 accessSecret 失败', err)
        },
      }
    default:
      return {
        getOssAccess: () => getOssAccess(bucketName),
        onFailure: (err: any) => {
          console.warn(`获取 oss ${bucketName} 桶 accessSecret 失败`, err)
        },
      }
  }
}

const downloadFile = async () => {
  if (!oss.value) return
  await oss.value.downloadFile('Frontend-Upload/common/ai.png')

  await oss.value.downloadFile(
    'bill/storage-bill/20250603/190539618/仓储账单2025-06-03.xlsx',
    getBucketOptionsByName('elnkproqa'),
  )
}
onMounted(async () => {
  //使用默认桶 front-ljh 初始化oss客户端
  oss.value = (await client.initOssClient({
    ...getBucketOptionsByName('front-ljh'),
    bucketName: 'front-ljh',
  })) as Oss
  const url = await oss.value.getSignatureUrl(
    'Frontend-Upload/common/ai.png', //文件路径
  )
  console.log('url', url)
  //使用 elnkproqa 桶 获取文件下载链接，并重命名为 aaa.xlsx 以附件形式下载
  const url2 = await oss.value.getSignatureUrl(
    'bill/storage-bill/20250603/190539618/仓储账单2025-06-03.xlsx', //文件路径
    3600, //链接有效期1小时
    'aaa.xlsx', //重命名为aaa.xlsx
    'attachment', //以附件形式返回链接
  )
  console.log('url2', url2)
  const currentBucket = client.getCurrentBucketName()
  console.log(`当前使用的桶: ${currentBucket}`)
  const fileSize = await client.getOssFileSize(
    'Frontend-Upload/common/ai.png', //文件路径
  )
  console.log(`文件大小: ${fileSize} MB`)
})
</script>

<template>
  <button @click="downloadFile">下载图片</button>
</template>

<style scoped>
.logo {
  height: 6em;
  padding: 1.5em;
  will-change: filter;
  transition: filter 300ms;
}
.logo:hover {
  filter: drop-shadow(0 0 2em #646cffaa);
}
.logo.vue:hover {
  filter: drop-shadow(0 0 2em #42b883aa);
}
</style>

工具方法

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

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

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

注意事项

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

快速开始

使用示例

方法说明

initOssClient

put

extractZip

zip 文件上传示例

downloadFile

getSignatureUrl

getOssFileSize

deleteFile

pauseUpload

switchBucket

getCurrentBucketName

clearBucketCache

destroy

actionResponse

Vue3 项目中使用

支持多实例分片上传

多桶切换功能

功能说明

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

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

实际项目用例

工具方法

注意事项