@xinlei/uni-aliyun-oss-uploader

v1.0.0

Published

13 days ago

Reusable uni-app Aliyun OSS uploader for H5 and WeChat Mini Program.

0High
0Medium
0Low

xinlei

uni-app uniapp aliyun oss sts upload uploader component vue vue2 mini-program weixin h5

@xinlei/uni-aliyun-oss-uploader

一个适用于 uni-app 的阿里云 OSS 直传封装，包含：

JS 上传器：createUniOssUploader
Vue 上传组件：media-upload
支持 H5
支持 微信小程序
不内置任何业务接口请求，ossConfig 由外部传入

这个包现在不依赖 uview-ui，可以单独发布和使用。

安装

npm install @xinlei/uni-aliyun-oss-uploader ali-oss crypto-js

如果你是以自己的 npm 账号发布，请先修改 package.json 里的 name。

一、先理解 `ossConfig`

组件和上传器都不会自己请求 STS。你需要在业务层先请求后端接口，然后把返回结果传进来。

后端最终需要返回类似下面的结构：

const ossConfig = {
  region: 'oss-cn-hangzhou',
  bucket: 'example-bucket',
  accessKeyId: 'STS.xxxxx',
  accessKeySecret: 'xxxxx',
  stsToken: 'CAISxxxxx',
  expiration: '2026-04-01T12:00:00Z',
  dir: 'uploads/',
  cdn_img_url: 'https://cdn.example.com/'
}

必须字段：

region
bucket
accessKeyId
accessKeySecret
stsToken
expiration

可选字段：

dir
cdn_img_url

二、上传器用法

1. 导入

import { createUniOssUploader } from '@xinlei/uni-aliyun-oss-uploader'

2. 创建实例

const ossUploader = createUniOssUploader({
  toast(message) {
    uni.showToast({
      title: message,
      icon: 'none'
    })
  }
})

3. 业务层获取 `ossConfig`

async function getOssConfig() {
  const res = await uni.$u.api.getOssStsToken()

  if (res && res.resp_code === '0000' && res.data) {
    return res.data
  }

  return null
}

4. 上传文件

const ossConfig = await getOssConfig()

const fileUrl = await ossUploader.uploadToOss(tempFilePath, {
  ossConfig
})

5. 也可以先缓存后再上传

const ossConfig = await getOssConfig()

ossUploader.setOssConfig(ossConfig)

const fileUrl = await ossUploader.uploadToOss(tempFilePath)

三、组件用法

1. 导入组件

import MediaUpload from '@xinlei/uni-aliyun-oss-uploader/media-upload'

也可以：

import MediaUpload from '@xinlei/uni-aliyun-oss-uploader/media-upload.vue'

2. 在页面中注册

import MediaUpload from '@xinlei/uni-aliyun-oss-uploader/media-upload'

export default {
  components: {
    MediaUpload
  }
}

3. 准备一个获取 `ossConfig` 的方法

methods: {
  async prepareOssConfig() {
    const res = await uni.$u.api.getOssStsToken()

    if (res && res.resp_code === '0000' && res.data) {
      return res.data
    }

    this.$u.toast('获取上传凭证失败')
    return null
  }
}

4. 最简单的图片上传示例

<media-upload
  :show-video="false"
  :get-oss-config="prepareOssConfig"
  :default-images="imageList"
  @image-change="handleImageChange"
/>

export default {
  data() {
    return {
      imageList: []
    }
  },
  methods: {
    handleImageChange(list) {
      this.imageList = list
    }
  }
}

5. 单卡片上传示例

适合“点击拍照”“单张图片”“单个视频”这种场景。

<media-upload
  :show-video="false"
  :show-label="false"
  layout="single-box"
  :max-image-count="1"
  :show-remove="false"
  :preview-enabled="false"
  :image-source-type="['camera']"
  :get-oss-config="prepareOssConfig"
  :default-images="imageUrl ? [imageUrl] : []"
  empty-image-icon="camera"
  empty-image-text="点击拍照"
  @image-change="handleImageChange"
/>

6. 视频上传示例

<media-upload
  :show-image="false"
  :show-label="false"
  layout="single-box"
  :max-video-count="1"
  :max-video-duration="10"
  :video-source-type="['camera', 'album']"
  :video-controls="true"
  :video-show-center-play-btn="true"
  :get-oss-config="prepareOssConfig"
  :default-videos="videoUrl ? [videoUrl] : []"
  empty-video-icon="plus-circle"
  empty-video-text="点击上传视频"
  @video-change="handleVideoChange"
/>

四、组件完整参数说明

通用参数

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | showImage | Boolean | true | 是否显示图片上传区域 | | showVideo | Boolean | true | 是否显示视频上传区域 | | showLabel | Boolean | true | 是否显示标题文字 | | disabled | Boolean | false | 是否禁用点击上传 | | layout | String | 'grid' | 布局模式，支持 grid、single-box | | showRemove | Boolean | true | 是否显示删除按钮 | | previewEnabled | Boolean | true | 是否允许预览 | | boxMinHeight | String | '160rpx' | single-box 模式下上传框最小高度 | | loadingText | String | '上传中...' | 上传时 loading 文案 |

凭证参数

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | ossConfig | Object | null | 直接传入当前上传凭证 | | getOssConfig | Function | null | 异步获取上传凭证的方法，优先级高于 ossConfig | | uploadFn | Function | null | 自定义上传方法，默认内部调用 createUniOssUploader |

uploadFn 调用签名：

async function uploadFn(filePath, { ossConfig }) {
  return fileUrl
}

图片参数

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | imageLabel | String | '上传照片 (选填)' | 图片区域标题 | | maxImageCount | Number | 3 | 最多上传图片数量 | | defaultImages | Array | [] | 默认图片列表 | | emptyImageText | String | '添加照片' | 图片空状态文案 | | emptyImageIcon | String | 'camera' | 图片空状态图标标识，仅用于内部样式区分 | | imageSourceType | Array | ['album', 'camera'] | uni.chooseImage 的来源配置 | | imageSizeType | Array | ['compressed'] | uni.chooseImage 的尺寸配置 |

视频参数

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | videoLabel | String | '上传视频 (选填)' | 视频区域标题 | | maxVideoCount | Number | 1 | 最多上传视频数量 | | maxVideoDuration | Number | 60 | 视频最长时长，单位秒 | | defaultVideos | Array | [] | 默认视频列表 | | emptyVideoText | String | '添加视频' | 视频空状态文案 | | emptyVideoIcon | String | 'play-circle' | 视频空状态图标标识，仅用于内部样式区分 | | videoSourceType | Array | ['camera', 'album'] | uni.chooseVideo 的来源配置 | | videoCompressed | Boolean | true | 是否压缩视频 | | videoControls | Boolean | false | 单卡片视频预览时是否显示 controls | | videoShowCenterPlayBtn | Boolean | false | 单卡片视频预览时是否显示中间播放按钮 |

五、组件事件

| 事件名 | 回调参数 | 说明 | | --- | --- | --- | | image-change | list | 图片列表变化时触发 | | video-change | list | 视频列表变化时触发 | | change | { type, value } | 任意媒体变化时统一触发 |

change 示例：

{
  type: 'image',
  value: ['https://example.com/a.jpg']
}

六、组件方法

通过 ref 可以调用：

`clear()`

清空当前组件中的图片和视频列表。

<media-upload ref="mediaUpload" />

this.$refs.mediaUpload.clear()

七、上传器 API

`createUniOssUploader(options)`

支持参数：

ossConfig：可选，初始化时直接写入凭证
toast(message)：可选，自定义错误提示
logger：可选，自定义日志对象
maxFileSize：可选，小程序上传大小限制，默认 104857600
resolveObjectKey(context)：可选，自定义 OSS object key
resolveFileUrl(context)：可选，自定义最终访问地址
messages：可选，自定义错误文案

`uploader.setOssConfig(ossConfig)`

手动设置上传凭证。

`uploader.clearOssConfig()`

清空已缓存的上传凭证。

`uploader.isOssConfigExpired(ossConfig?)`

判断凭证是否过期。

`uploader.generateFileName(filePath, uploadOptions?)`

默认命名规则：

${dir}${timestamp}_${random}.${ext}

`uploader.uploadToOss(filePath, uploadOptions?)`

上传文件并返回最终访问 URL。

uploadOptions 支持：

ossConfig
fileName
formFieldName
formData
maxFileSize
onProgress(progress)

八、推荐项目接入方式

推荐把“获取凭证”放在你自己的业务层：

import ossUpload from '@/utils/oss-upload.js'

async function uploadFile(tempFilePath) {
  const res = await uni.$u.api.getOssStsToken()
  const ossConfig = res && res.resp_code === '0000' ? res.data : null

  if (!ossConfig) {
    uni.showToast({
      title: '获取上传凭证失败',
      icon: 'none'
    })
    return null
  }

  return ossUpload.uploadToOss(tempFilePath, { ossConfig })
}

九、发布

1. 发布前检查

先确认下面几项：

package.json 里的 name 是你要发布的 npm 包名
package.json 里的 version 已经正确递增
README.md、index.js、media-upload.vue 都是最终版本
npm run check:pack 可以通过

执行：

cd packages/uni-aliyun-oss-uploader
npm run check:pack

2. 登录 npm

npm login
npm whoami

npm whoami 能输出你的用户名，说明登录成功。

3. 正式发布

cd packages/uni-aliyun-oss-uploader
npm publish

因为 package.json 里已经配置了：

"publishConfig": {
  "access": "public",
  "registry": "https://registry.npmjs.org/"
}

所以一般不需要再手动写 --access public，也会默认发到 npm 官方仓库。

如果你机器上配置过其他镜像源，发布前可以顺手确认一下：

npm config get registry

正常应该看到：

https://registry.npmjs.org/

4. 后续再次发布

每次重新发布前，先升级版本号：

npm version patch

也可以根据需要使用：

npm version patch
npm version minor
npm version major

版本更新后再执行：

npm publish

5. 安装验证

发布成功后可以单独验证一次：

npm install @xinlei/uni-aliyun-oss-uploader

如果你之后换了 scope 或包名，README 里的安装命令和导入示例也要一起更新。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xinlei/uni-aliyun-oss-uploader

安装

一、先理解 ossConfig

二、上传器用法

1. 导入

2. 创建实例

3. 业务层获取 ossConfig

4. 上传文件

5. 也可以先缓存后再上传

三、组件用法

1. 导入组件

2. 在页面中注册

3. 准备一个获取 ossConfig 的方法

4. 最简单的图片上传示例

5. 单卡片上传示例

6. 视频上传示例

四、组件完整参数说明

通用参数

凭证参数

图片参数

视频参数

五、组件事件

六、组件方法

clear()

七、上传器 API

createUniOssUploader(options)

uploader.setOssConfig(ossConfig)

uploader.clearOssConfig()

uploader.isOssConfigExpired(ossConfig?)

uploader.generateFileName(filePath, uploadOptions?)

uploader.uploadToOss(filePath, uploadOptions?)

八、推荐项目接入方式

九、发布

1. 发布前检查

2. 登录 npm

3. 正式发布

4. 后续再次发布

5. 安装验证

一、先理解 `ossConfig`

3. 业务层获取 `ossConfig`

3. 准备一个获取 `ossConfig` 的方法

`clear()`

`createUniOssUploader(options)`

`uploader.setOssConfig(ossConfig)`

`uploader.clearOssConfig()`

`uploader.isOssConfigExpired(ossConfig?)`

`uploader.generateFileName(filePath, uploadOptions?)`

`uploader.uploadToOss(filePath, uploadOptions?)`