更新记录

0.1.0（2026-08-25）

• 实现 Android Storage Access Framework 系统保存面板与流式文件写入。
• 实现 iOS 系统文档导出面板与网络、本地文件暂存。
• 支持 HTTP/HTTPS、本地绝对路径、file URL，以及 Android content URI。
• 新增任务 ID、字节进度、总量进度、主动取消和系统面板取消结果。
• 新增参数校验、文件名清洗、唯一后缀策略和单任务并发保护。
• 新增交互式导出终端示例页、API 文档与双端真机测试清单。
• 通过 Android、iOS 插件模块及 uni-app x 整项目编译。

平台兼容性

uni-app x(4.0)

xs-file-exporter

面向 uni-app x App 的系统文件导出 UTS API 插件。适合“另存为”、报告下载、日志导出、离线包交付和用户自主选择文件位置等场景。

支持平台

• Android 5.0（API 21）及以上。
• iOS 12.0 及以上。
• 已编译验证：uni-app x App-Android、App-iOS。
• Web、小程序和 HarmonyOS 暂不支持。

快速使用

import {
  exportFile,
  cancelFileExport,
  FileExportProgress,
  FileExportResult
} from '@/uni_modules/xs-file-exporter'

const taskId = exportFile({
  source: 'https://example.com/report.pdf',
  fileName: 'report.pdf',
  mimeType: 'application/pdf',
  conflictStrategy: 'ask'
}, (progress : FileExportProgress) => {
  console.log(progress.bytesWritten, progress.totalBytes, progress.progress)
}, (result : FileExportResult) => {
  console.log(result.saved, result.uri, result.cancelled)
}, (error : string) => {
  console.error(error)
})

// 用户主动停止或页面销毁时调用
cancelFileExport(taskId)

详细字段、错误码和平台差异见示例工程的 docs/API.md。

来源与进度

• 双端支持 HTTP/HTTPS URL、本地绝对路径和 file:// URL。
• Android 额外支持具有有效读取授权的 content:// URI。
• Android 在用户选择位置后直接流式写入目标；iOS 先流式写入临时目录，再打开系统文档导出面板。
• 来源没有 Content-Length 或可读文件大小时，totalBytes 和 progress 为 null，bytesWritten 仍会更新。
• 同一时刻只允许一个导出任务；并发调用通过失败回调返回 BUSY。

重名语义

• rename 会在扩展名前添加毫秒时间后缀，作为系统面板的唯一文件名建议。
• ask 与 overwrite 保留调用方文件名。Android DocumentsProvider 和 iOS 文档提供方拥有最终重名处理权，可能覆盖、询问或自动改名；插件不会绕过系统面板强制覆盖文件。

权限与隐私

• Android 仅自动合并普通权限 android.permission.INTERNET，不申请存储运行时权限。
• iOS 不申请用户授权权限；HTTP 明文访问仍受宿主 ATS 配置控制。
• 插件仅读取或下载调用方明确传入的来源，不内置上报地址、不主动上传文件。

能力边界

取消或失败发生在 Android 已创建目标 URI 之后时，部分文件提供方可能保留空文件或部分文件。插件不会自动删除该 URI，因为系统提供方也可能把它映射到用户已有文件。正式上架前应在目标用户常用的文件管理器、网盘提供方、弱网和大文件场景中完成真机验证。