更新记录

V1.2.0（2026-05-21） 下载此版本

1.新增 appAction 参数。 2.share：保持原来的 APP 系统分享逻辑。 3.save：APP 只保存文件，不打开分享面板。 4.Android 保存前增加存储权限检查。 5.保存成功后返回 path / localPath / filename / size / action。 6.新增 saveDirName，可以控制保存文件夹名。

V1.1.2（2026-04-23） 下载此版本

1.修复引入报错兼容问题

V1.1.1（2026-04-23） 下载此版本

1.修复多层打包问题

查看更多

平台兼容性

uni-app(4.87)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
× √ √ √ √ - √ √ ×
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

文件下载与系统分享

用于 uni-app 项目中的文件下载、APP 系统分享、APP 保存到手机文件管理的 JS SDK 插件。支持 ArrayBuffer 二进制文件流 和 在线 URL 资源 两种方式处理文件。

插件会根据运行环境自动选择处理逻辑：

  • H5：浏览器直接下载
  • Android APP：支持系统分享，也支持保存到手机文件管理目录
  • iOS APP：支持系统分享，也支持保存到 App 沙盒文件目录

支持文件类型包括：

  • Excel
  • PDF
  • Word
  • 图片
  • 视频
  • ZIP
  • 其他常见二进制文件

功能特点

  • 支持 ArrayBuffer 文件流下载、分享、保存
  • 支持在线文件 URL 下载、分享、保存
  • 支持图片、视频、PDF、Excel、Word、ZIP 等常见文件类型
  • 兼容 H5、Android、iOS
  • 保留原有调用方式，旧代码不传新参数仍然默认系统分享
  • 自动根据文件名推断 mime
  • Android 支持 FileProvider 分享
  • Android 保存文件前会检查存储权限
  • 保存成功后返回文件路径、相对路径、文件名、文件大小

核心新增参数

APP 端新增 appAction 参数，用来控制 APP 环境下的行为。

参数值 说明
share 默认值。APP 端写入本地后调起系统分享
save APP 端只保存到手机文件管理目录，不调起系统分享

不传 appAction 时，默认仍然是 share，不会影响旧项目。

APP 保存相关配置

字段 类型 必填 默认值 说明
appAction string 否 share APP 端行为：share / save
saveDirName string 否 file_save 保存文件夹名称
saveBaseRoot string 否 Android _downloads/，iOS _doc/ 保存根目录
shareDirName string 否 share_temp 系统分享临时目录名称
shareBaseRoot string 否 Android _downloads/，iOS _doc/ 分享临时文件根目录

返回值

{
  platform: 'H5' | 'Android' | 'iOS',
  action: 'download' | 'share' | 'save',
  path: string,
  localPath: string,
  filename: string,
  size: number
}

字段说明：

字段 说明
platform 当前处理平台
action 当前执行动作
path APP 端为本地绝对路径；H5 URL 下载时为原始 URL
localPath plus 本地相对路径，例如 _downloads/file_save/test.pdf
filename 最终文件名
size 文件大小，单位 byte

安装后可用方法

1. downloadOrShareArrayBuffer

处理二进制文件流。

downloadOrShareArrayBuffer(buffer, filename, options)

2. downloadOrShareByUrl

处理在线文件地址。

downloadOrShareByUrl(url, options)

3. shareOnlineImage

处理在线图片地址。

shareOnlineImage(url, options)

4. shareOnlineVideo

处理在线视频地址。

shareOnlineVideo(url, options)

5. shareResource

统一入口方法。

shareResource(params)

引入方式

import {
  downloadOrShareArrayBuffer,
  downloadOrShareByUrl,
  shareOnlineImage,
  shareOnlineVideo,
  shareResource
} from '@/utils/download-share'

请按你的实际插件安装路径调整导入地址。

基础用法

一、APP 默认系统分享，旧逻辑不变

await downloadOrShareArrayBuffer(buffer, '报表.xlsx', {
  mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  chooserTitle: '分享Excel'
})

不传 appAction，默认等价于：

await downloadOrShareArrayBuffer(buffer, '报表.xlsx', {
  appAction: 'share',
  mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  chooserTitle: '分享Excel'
})

二、APP 保存文件流到手机文件管理

const result = await downloadOrShareArrayBuffer(buffer, '报表.xlsx', {
  appAction: 'save',
  saveDirName: 'HugeAuto',
  mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
})

console.log('保存成功路径：', result.path)
console.log('本地相对路径：', result.localPath)

返回示例：

{
  platform: 'Android',
  action: 'save',
  path: '/storage/emulated/0/Download/HugeAuto/报表.xlsx',
  localPath: '_downloads/HugeAuto/报表.xlsx',
  filename: '报表.xlsx',
  size: 10240
}

三、APP 保存在线 PDF 到手机文件管理

const result = await downloadOrShareByUrl('https://example.com/test.pdf', {
  appAction: 'save',
  saveDirName: 'HugeAuto',
  filename: '说明文档.pdf',
  mime: 'application/pdf'
})

uni.showToast({
  title: '保存成功',
  icon: 'success'
})

console.log(result.path)

四、APP 系统分享在线图片

await shareOnlineImage('https://example.com/test.png', {
  appAction: 'share',
  filename: '商品图片.png',
  chooserTitle: '分享图片'
})

五、APP 保存在线视频

const result = await shareOnlineVideo('https://example.com/test.mp4', {
  appAction: 'save',
  saveDirName: 'HugeAuto',
  filename: '演示视频.mp4'
})

console.log('视频保存路径：', result.path)

六、统一入口方式

传入文件流并保存

const result = await shareResource({
  buffer,
  filename: '报表.xlsx',
  appAction: 'save',
  saveDirName: 'HugeAuto',
  mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
})

console.log(result.path)

传入 URL 并分享

await shareResource({
  url: 'https://example.com/test.pdf',
  filename: '文档.pdf',
  appAction: 'share',
  mime: 'application/pdf',
  chooserTitle: '分享PDF'
})

在 uni-app 页面中的使用示例

<script setup>
import {
  downloadOrShareArrayBuffer,
  downloadOrShareByUrl
} from '@/utils/download-share'

const handleSaveExcel = async () => {
  try {
    const res = await uni.request({
      url: 'https://example.com/export',
      method: 'GET',
      responseType: 'arraybuffer'
    })

    const result = await downloadOrShareArrayBuffer(res.data, '报表.xlsx', {
      appAction: 'save',
      saveDirName: 'HugeAuto',
      mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
    })

    uni.showToast({
      title: '保存成功',
      icon: 'success'
    })

    console.log('保存路径：', result.path)
  } catch (e) {
    uni.showToast({
      title: e.message || '保存失败',
      icon: 'none'
    })
  }
}

const handleSharePdf = async () => {
  try {
    await downloadOrShareByUrl('https://example.com/test.pdf', {
      appAction: 'share',
      filename: '说明文档.pdf',
      mime: 'application/pdf',
      chooserTitle: '分享PDF'
    })
  } catch (e) {
    uni.showToast({
      title: e.message || '分享失败',
      icon: 'none'
    })
  }
}
</script>

MIME 参考

Excel

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
application/vnd.ms-excel

PDF

application/pdf

Word

application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/msword

图片

image/png
image/jpeg
image/webp

视频

video/mp4
video/quicktime

权限说明

Android

保存到手机文件管理时，插件会在 APP 端自动执行权限检查。

根据 Android 版本和项目 targetSdk，可能需要在 manifest.json 或原生工程中配置：

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Android 9 及以下写入外部下载目录通常需要 WRITE_EXTERNAL_STORAGE。Android 10+ 受分区存储影响，动态权限不一定生效，最终以实际写入和文件校验结果为准。

iOS

iOS 无强制存储权限。插件默认写入 _doc 目录，属于 App 沙盒目录。若希望用户在 iOS「文件」App 中直接看到文档，需要原生侧额外开启文件共享相关配置。

注意事项

1. 旧调用方式不受影响

旧代码不传 appAction 时，APP 端仍然调起系统分享。

2. 保存文件建议传完整文件名

建议传入完整文件名，例如：

  • 报表.xlsx
  • 文档.pdf
  • 图片.png
  • 视频.mp4

这样插件可以更准确推断文件类型。

3. 保存路径

Android 默认保存到：

_downloads/file_save/文件名

可以通过 saveDirName 改成：

_downloads/HugeAuto/文件名

iOS 默认保存到：

_doc/file_save/文件名

4. URL 资源需可访问

如果传入的是在线文件地址，必须保证该地址可正常访问，否则下载会失败。

5. 接口返回文件流时需使用 arraybuffer

responseType: 'arraybuffer'

6. Android FileProvider 需正确配置

系统分享依赖 FileProvider。如果分享失败，请检查 Android 原生工程中的 FileProvider 配置。

7. 建议增加防重复点击

实际业务中建议在分享或保存按钮点击后增加 loading 状态，避免重复触发。

常见问题

Q1：appAction: 'save' 会不会弹出系统分享？

不会。save 只保存文件并返回路径。

Q2：不传 appAction 会怎样？

默认是 share，也就是原来的 APP 系统分享逻辑。

Q3：保存成功后怎么拿路径？

const result = await downloadOrShareByUrl(url, {
  appAction: 'save',
  filename: 'test.pdf'
})

console.log(result.path)

Q4：保存失败怎么办？

捕获异常并提示：

try {
  await downloadOrShareByUrl(url, {
    appAction: 'save',
    filename: 'test.pdf'
  })
} catch (e) {
  uni.showToast({
    title: e.message || '保存失败',
    icon: 'none'
  })
}

Q5：H5 支持 appAction: 'save' 吗？

H5 不区分 share / save，统一走浏览器下载。

推荐调用方式

APP 系统分享

await downloadOrShareByUrl(url, {
  appAction: 'share',
  filename: '文档.pdf'
})

APP 保存到手机文件管理

const result = await downloadOrShareByUrl(url, {
  appAction: 'save',
  saveDirName: 'HugeAuto',
  filename: '文档.pdf'
})

console.log(result.path)

不想区分文件来源

const result = await shareResource({
  url,
  filename: '文档.pdf',
  appAction: 'save'
})

隐私、权限声明

1. 本插件需要申请的系统权限列表：

Android READ_MEDIA_FILES WRITE_MEDIA_FILES READ_EXTERNAL_STORAGE（仅 targetSdk < 33 时可选） iOS 无强制权限（文件写入 _doc 属于App沙盒）

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

1）采集的数据 本插件采集/处理： 宿主App下载接口返回的 ArrayBuffer 文件名称 filename 系统类型 plus.os.name 2）发送的服务器地址 本插件自身不主动请求服务器，仅处理宿主App提供的接口数据。 示例宿主调用地址： https://<宿主业务域名>/version/specs/share 真实服务器地址由使用方在App中配置，本插件不内置固定域名。 3）数据用途 用途说明： 数据 用途 ArrayBuffer 还原原始文档 filename 创建文件 平台类型 选择分享方式 不会： 采集设备IMEI/OAID 不发送任何隐私信息 不包含行为追踪

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

许可协议

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

评论列表 撰写评论 向官方投诉
加载更多...