@aplus-frontend/oss

Aplus 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 = client.initOssClient({
  you_STS_server,
  onFailure: err => {
    console.warn('get oss accessSerct fail', err)
  }
})

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

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


// upload image or vedio with oss
// your can use put method to upload
const result = await client.put({
  fileName: file.name,
  dirName: 'Vedio',
  data: file,
  progressCallBack: (p: number) => {
    percentVeido.value = p
  },
  //the number of parts to be uploaded in parallel
  parallel: 6,
  //the suggested size for each part, defalut 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 perview 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: ResquestOssOptions): Promise<Oss>; d 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

put

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

tips: you can put image vedio 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, defalut 1024 _ 1024(1MB), minimum 100 _ 1024(100KB)

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): Promise<actionResponse>

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

downloadFile options

Props	Type	default	explanation
savePathName	Array<string> | string	-	if mutipart download will be arrary,single file download wille be string

getSignatureUrl

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

tips: get signature url to perview

getSignatureUrl options

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

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 vedio after uploaded
saveUrl	string	-	your backend server wille 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 mutipart upload

support mutipart upload with exports createOssInstance method to create mutipart 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()