@aplus-frontend/oss

Repackaged ali-oss sdk to make it easier to upload files to Alibaba Cloud oss

Quick start

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

Usage example

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

//some code in you project
import { you_STS_server } from '@/api/sts'

//init oss access token
const ossIntsance = await client.initOssClient({
  you_STS_server,
  onFailure: err => {
    console.warn('get oss accessSecret fail', err)
  }
})

//after init
//you can use ossIntsance do something

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


// upload image or video with oss
// your can use put method to upload
const result = await client.put({
  fileName: file.name,
  dirName: 'video',
  data: file,
  progressCallBack: (p: number) => {
    percentVideo.value = p
  },
  //the number of parts to be uploaded in parallel
  parallel: 6,
  //the suggested size for each part, default 1024 * 1024(1MB), minimum 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 {
  //failure
  console.log(result.message)
}

//you can use download method to download
let res = client.downloadFile(fileName)
console.log(res.message)
console.log(res.status)
//you can  get signature url to preview with  getSignatureUrl method
let signatureUrl = client.getSignatureUrl(pathName)
//get signature url
//after expires seconds, the url will become invalid, default is 3600s
console.log(signatureUrl)

//delete file
let res = await client.deleteFile(pathName)
console.log(res)

//pauseUpload
let res = = await client.pauseUpload()
console.log(res)

Methods

initOssClient

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

tips: register client instance with you sts server

ResquestOssOptions

props	type	default	directions
getOssAccess	`() => Promise<accessCreate>`	-	init oss access token
onFailure	`(err: any) => void`	-	get oss accessSerct fail
locale	`zh_CN \| en_US`	`zh_CN`	language
bucket	`string`	`-`	（not required）choose bucket where to upload in ali-yun oss

put

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

tips: you can put image video with put core method

put options

Props	Type	default	explanation
fileName	`string`	-	file Name
dirName	`string`	-	upload folder name
data	`File`	-	upload data
progressCallBack	`(p:number) => void`	-	upload progress
parallel	`number`	6	the number of parts to be uploaded in parallel
partSize	`number`	1024*1024(1M)	the suggested size for each part, default 1024 _ 1024(1MB), minimum 100 _ 1024(100KB)
expires	`number`	1800	after expires seconds, the url will become invalid, default is 1800
needHash	`boolean`	true	hash upload file name

extractZip

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

tips: The zip file will be decompressed with extractZip methods ,After that you want to upload to Ali oss one by one through the put method by yourself.

extractZip options

Props	Type	default	explanation
file	`File`	-	file data

extract zip file demo

//upload zip file demo

//template
 <input type="file" @change="onFileChange" />

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

downloadFile

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

tips: download file with downloadFile method (support multiple download files)

downloadFile options

Props	Type	default	explanation
savePathName	`Array<string> \| string \| Array<{path: string;fileName: string;}>`	-	if multipart download will be array,single file download will be string

getSignatureUrl

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

tips: get signature url to preview

getSignatureUrl options

Props	Type	default	explanation
name	`string`	-	file path name
expires	`number`	3600(s)	expires time
rename	`string`	-	customized file name

deleteFile

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

tips: delete oss file

deleteFile options

Props	Type	default	explanation
savePathName	`string`	-	file path name
isRealDelete	`boolean`	`false`	In order to avoid accidentally deleting oss files, developers must manually turn on isRealDelete=true when deleting files. The default is false.

pauseUpload

type: pauseUpload(): Promise<actionResponse>;

tips: pause upload

destroy

type: destroy(): Promise<actionResponse>

tips: destroy oss instance

actionResponse

Props	Type	default	explanation
status	`number`	-	status code(success 200 ,other will be fail)
previewUrl	`string`	-	preview file url,you can preview image or video after uploaded
saveUrl	`string`	-	your backend server will be save this path
message	`string`	-	success message or fail message
originalFileName	`string`	-	upload file original name

How to use in project with Vue3

You can write useOss.ts global Hooks like below

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

you need to download or upload functionality in your application you can use like this

  import { useOssInit, useOss } from '@/hooks/web/useOss';
  //oss not init
  //your can use useOssInit to initial
  useOssInit();
  //after initial you can use useOss to get client instance
  const { client } = useOss();

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

support multipart upload

support multipart upload with exports createOssInstance method to create multipart upload instance

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

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

const client2 = createOssInstance()
client2.put(...)
//stop client1 upload
client1.pauseUpload()
//stop client2 upload
client2.pauseUpload()