更新记录

1.0.0（2026-10-27）

插件定位与版本

承接原 SDK 的文件流保存、URL 下载、系统分享及模拟数据能力，同时增加 UTS 接口、蒸汽模式演示与稳定性优化。
新包包含完整 JS 兼容入口，无需安装或依赖旧 SDK；新旧插件可以同时安装，已有项目可按需迁移。

文件下载、保存与系统分享

支持将接口返回的 ArrayBuffer 保存为本地文件，或写入文件后调起系统分享，覆盖 Excel、PDF、Word、PPT、ZIP、TXT、CSV、图片、视频等文件场景。
支持在线文件 URL 下载后保存或分享，保留显式指定文件名、MIME、保存目录和分享标题等配置。
保留 downloadOrShareArrayBuffer、downloadOrShareByUrl、shareOnlineImage、shareOnlineVideo、shareResource、getResourceTypeByFilename 六个基础 API。
shareResource 支持文件流与在线地址两种数据来源；同时提供时优先使用文件流。资源分类接口返回 image、video 或 file。
保留 appAction: 'share' 默认分享行为；appAction: 'save' 只保存、不打开分享面板，download 继续作为保存动作的兼容别名。
支持 saveDirName、shareDirName 自定义保存 / 分享目录，以及 chooserTitle 自定义系统分享标题。
Web / H5 使用 Blob 触发浏览器下载；UTS 原生入口保存到应用沙盒，并返回文件路径、文件名、大小（字节数）、平台和动作等信息。
Android UTS 使用原生文件写入与 Intent / FileProvider 分享；iOS / 鸿蒙保留系统分享及打开文档的降级处理。

旧版能力与 JS 兼容入口

提供显式 @/uni_modules/lf-file-share-uts/index.js 入口，保留传统 uni-app Vue2 / Vue3、App-vue、nvue 与 H5 的原 SDK 调用方式。
保留旧 JS 默认导出对象、命名导出、模拟数据、try* 包装及原有参数 / 返回字段约定。
JS 兼容入口继续支持 ArrayBuffer、TypedArray、DataView 和跨 realm ArrayBuffer；按视图的 byteOffset / byteLength 提取实际数据，避免保存整个底层 Buffer。
保留旧 Android 公共 Download 默认保存行为及 saveLocation: 'sandbox' 沙盒选项；旧系统公共目录所需权限要求保持不变。
保留 iOS / 鸿蒙沙盒保存和 H5 下载行为。UTS 根入口与 JS 兼容入口的保存位置差异在使用说明中明确列出。
保留 platform、action、path、localPath、filename、size、isPublic 等结果约定，以及可选路径 / URI 字段；UTS 原生沙盒返回 isPublic:false。
旧 SDK 的运行代码与旧 demo 保持原样；迁移时通过调整导入路径选择新版 UTS 或 JS 兼容入口。

uni-app x 与蒸汽模式适配

新增标准 UTS 根入口 @/uni_modules/lf-file-share-uts，提供统一的 options、资源参数、返回结果和操作结果类型声明。
新 x 演示页采用 <script setup lang="uts"> 组合式 API，适配 Vapor（蒸汽模式）对组合式页面的要求，同时保留 VDOM 用法。
原生平台能力封装在 UTS 插件内部，演示页面通过公开 API 调用保存与分享，减少页面与原生实现的耦合。
新 x 页面使用简单 class 样式和显式滚动配置，处理窗口尺寸变化及底部安全区；隔离验证工程启用样式隔离策略 2.0。
新版不会自动切换旧业务工程的渲染模式；业务中其他页面和组件的蒸汽适配仍需分别处理。

类型与错误处理

UTS 入口补齐 tryDownloadOrShareArrayBuffer、tryDownloadOrShareByUrl、tryShareOnlineImage、tryShareOnlineVideo、tryShareResource 五个不抛错接口。
try* 成功返回 { ok:true, code:'ok', message:'ok', ...result }，失败返回 { ok:false, code, message }，方便统一展示操作状态。
基础接口保留原有同步 / 异步返回与抛错约定；可选 options 仍支持省略。
补充 LfFileShareOptions、LfFileShareResourceParams、LfFileShareResult、LfFileShareOutcome 等 UTS 类型。
下载、读取、准备目录、写入及系统分享失败时保留对应阶段信息和原始错误说明，文件处理错误包含相关路径，便于定位问题。
保留默认关闭的 debug 参数；启用后输出处理阶段、耗时与字节数。

稳定性修复与细节优化

UTS 原生 URL 下载采用 uni.downloadFile 获取临时文件，再按二进制读取，避免部分 Android 环境把请求响应 String 强转为 ArrayBuffer 导致异常。
Android 使用原生应用数据目录及 ByteBuffer / FileChannel 写入，写入完成后校验文件长度，避免虚拟路径误用和大文件空写。
Android 7.0+ 的 FileProvider 授权失败时返回具体错误，移除可能触发 FileUriExposedException 的 file:// 静默兜底。
完善文档、压缩包、图片和视频的 MIME 推断与资源分类，补齐 GIF、WebP、BMP、HEIC、MOV、AVI、MKV、WebM 等常用扩展名识别。
保留调用者指定的 MIME，修复图片 / 视频快捷方法覆盖自定义 MIME 的问题；无合法后缀时按 MIME 补齐，已有合法后缀继续保留。
URL 文件名提取时剥离查询参数和片段标识、处理 URI 编码，并保留显式 filename 的优先级。
文件名去除控制字符、替换非法路径字符并清理首尾空白；超长文件名截断时保留扩展名。
保存 / 分享目录单独规范化，纯点目录名和空名称回退到安全默认目录，避免拼接到上级路径。
修复 iOS 用户取消分享后仍打开文档的问题：收到取消错误时直接结束当前请求，交由调用方处理，不再触发打开文档降级。
修复实际 Kotlin 编译发现的 URI 解码可空返回和 demo TypedArray 写入签名问题。

模拟数据与真实文件样例

JS 兼容入口保留 MOCK_FILES、文件列表、模拟表格导出、按文件 ID 导出、大文件 / 大图模拟请求等原 SDK 能力。
保留 XLSX、TXT、CSV、PDF、PNG、BMP、BIN 等本地生成方法，以及 UTF-8 / Base64 转 ArrayBuffer 和文件大小格式化工具。
新 x demo 使用私有 UTS 数据工厂，替换原先仅填充任意字节再修改扩展名的样例，生成可被对应格式读取器解析的真实文件。
XLSX 使用有效 ZIP / XML 工作簿结构，包含中文商品及金额；大表格提供 1,500 条真实数据。
大图生成 1,280 × 720 BMP 像素数据，大文件生成约 2.5 MiB BIN；CSV / TXT 使用 UTF-8，x 本地文本样例覆盖中文和 emoji。
两套新 demo 的 PDF 使用正确的对象引用、xref 偏移、startxref 和流长度，修复新演示流程继承的 PDF 结构问题，同时保持旧兼容 mock 原样。
本地样例生成无需后端或外网；在线 URL 演示仍需要网络。

Demo 重设计与交互优化

新增传统 uni-app 与 uni-app x 两套独立演示页，路由为 pages/file-share-uts/demo，旧版演示路由继续保留。
统一浅色工具页布局、品牌绿主操作、文件类型标识、分组标题及结果展示，突出接口表格导出的核心流程。
保留销售报表、大 XLSX、大图 BMP、大文件 BIN、CSV、PDF、TXT、在线 PDF、本地文本九类场景，以及对应十八个保存 / 分享入口。
展示文件说明、处理阶段、结果文件名、实际大小和保存位置；支持复制本地路径及展开完整返回信息。
操作开始前先设置忙碌锁，再生成资源，避免连续点击重复分配大 Buffer；结束或失败后统一恢复操作状态，允许重试。
x 大资源按需延迟生成并缓存，页面卸载时释放缓存并使尚未开始的生成任务失效。
H5 下载、原生保存及系统分享使用对应结果文案，清楚区分浏览器下载位置、应用沙盒和公共 Download 目录。
系统分享结果只表示已处理系统请求，不将其描述为文件已送达目标应用。

使用说明与验证

使用说明中统一包含 API、参数、保存位置、JS / UTS 入口选择及旧版迁移步骤，无需单独查阅迁移文档。
新增新旧插件共存、单独安装及回退说明，保留复制代码的原版权与许可声明。
增加公开接口、错误传播、MIME / 路径处理、独立 JS 兼容调用、TypedArray 切片及取消分享等针对性测试。
使用独立格式检查验证 XLSX 的 ZIP CRC / XML 关联、BMP 解码、PDF 结构、UTF-8 内容及 BIN 长度。
当前 37 项自动测试通过，Android UTS 模块实际 Kotlin 编译及完整 VDOM 基座编译通过。
蒸汽模式已完成代码适配及对应工程配置下的 Android UTS 模块编译；

平台兼容性

uni-app(5.26)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
√	√	√	√	√	√	√	√	×

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
×	×	×	×	×	×	×	×	×	×	×	×

uni-app x(5.26)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
√	√	√	√	-	×

其他

多语言	暗黑模式	宽屏模式	蒸汽模式
×	×	×	√

文件下载与系统分享 UTS

lf-file-share-uts · 1.0.0。将接口返回的 ArrayBuffer 或在线 URL 保存为文件，或交给系统分享 / 打开。

选择入口

项目与用途	导入路径	能力
uni-app x，VDOM / 蒸汽页面	`@/uni_modules/lf-file-share-uts`	六个基础 API、五个 `try*`、UTS 类型
传统 uni-app Vue2 / Vue3 / nvue	`@/uni_modules/lf-file-share-uts/index.js`	保留旧 SDK 的默认对象、全部命名导出、mock、TypedArray、`try*`

开发和编译基线为 HBuilderX 5.26。传统 Android Vue 页面向 UTS 传 ArrayBuffer 存在桥接限制，请使用显式 JS 兼容入口。UTS 根入口不提供旧 JS 默认对象或公开 mock。

import { downloadOrShareArrayBuffer, downloadOrShareByUrl,
  tryDownloadOrShareByUrl } from '@/uni_modules/lf-file-share-uts'
import type { LfFileShareOptions } from '@/uni_modules/lf-file-share-uts'

const options: LfFileShareOptions = {
  appAction: 'save', mime: 'application/pdf',
  filename: '说明文档.pdf', saveDirName: 'MyApp', saveLocation: 'sandbox'
}
const result = await downloadOrShareByUrl('https://your.example/document.pdf', options)
console.log(result.path)

UTS 原生 URL 下载使用 downloadFile 后按二进制读取，避免把响应中的 String 强转为 ArrayBuffer。

API

方法	作用
`downloadOrShareArrayBuffer(buffer, filename, options?)`	保存或分享 ArrayBuffer
`downloadOrShareByUrl(url, options?)`	下载 URL 后保存或分享
`shareOnlineImage(url, options?)`	图片快捷入口，保留指定 MIME
`shareOnlineVideo(url, options?)`	视频快捷入口，保留指定 MIME
`shareResource(params)`	优先使用 buffer，否则使用 url
`getResourceTypeByFilename(filename?, mime?)`	返回 image / video / file

前五个方法对应 tryDownloadOrShareArrayBuffer、tryDownloadOrShareByUrl、tryShareOnlineImage、tryShareOnlineVideo、tryShareResource。

基础方法失败时抛错，try* 失败时返回 { ok:false, code, message }。
try* 成功返回 { ok:true, code:'ok', message:'ok', ...result }。
UTS 的错误 code 沿用 ok、fail、invalidParam、unsupported。

参数与返回

参数	默认值 / 说明
`appAction`	`share`；`save` 只保存，`download` 为 save 别名
`filename`	URL 场景显式指定时优先，否则从 URL 提取并解码
`mime`	显式值优先，否则按扩展名推断；无后缀时按 MIME 补齐
`chooserTitle`	系统分享标题
`saveDirName` / `shareDirName`	`file_save` / `share_temp`；规范化为单层目录名
`saveLocation`	UTS 入口保留兼容字段，原生端始终写沙盒，不提供公共 Download 保存
`debug`	默认 false；启用后输出阶段、耗时和字节数

原生返回 platform、action、path、localPath、filename、size、isPublic:false；保留可选的 absPath、relPath、uri 类型字段。Web 使用 Blob 下载，action:'download'，路径为空。

原生沙盒目录为应用数据目录下的 lf-file-share-uts/<目录名>。Android 通过 FileProvider 授予临时读取权限；缺少可用 Provider 时返回具体错误。iOS / 鸿蒙系统分享不可用时保留打开文档降级。API 返回成功只代表保存完成或系统处理请求完成，不代表目标应用已接收文件。

JS 兼容入口保留旧 Android 公共 Download 默认行为。Android 9 及以下写外部公共目录时，仍需配置和授予 WRITE_EXTERNAL_STORAGE / READ_EXTERNAL_STORAGE；saveLocation:'sandbox' 可选择沙盒。iOS / 鸿蒙保存到沙盒，H5 触发浏览器下载。

传统 JS 与 mock

import lfFileShare, {
  mockFetchExcelExport, downloadOrShareArrayBuffer
} from '@/uni_modules/lf-file-share-uts/index.js'

const payload = await mockFetchExcelExport({ filename: '销售报表.xlsx' })
const result = await downloadOrShareArrayBuffer(payload.data, payload.filename, {
  mime: payload.mime, appAction: 'save', saveDirName: 'MyApp'
})
console.log(result.path)

兼容文件与旧 SDK 保持一致，支持 ArrayBuffer / TypedArray、默认导出、旧 mock 和 try*。它们通过同包相对依赖运行，不依赖安装旧插件。

从旧 SDK 迁移

旧 SDK lf-file-share1.3.7版本后停止后续更新。新版独立安装到 lf-file-share-uts 目录，不覆盖旧包。

传统 uni-app Vue2 / Vue3 / nvue

原调用：

import share, { mockFetchExcelExport } from '@/uni_modules/lf-file-share/index.js'

替换为新包的兼容入口，函数、参数和结果处理保持原样：

import share, { mockFetchExcelExport } from '@/uni_modules/lf-file-share-uts/index.js'

如果原 JS 代码通过根路径导入默认对象或 mock，也改为新包显式 /index.js。新包根路径是 UTS 接口。TypedArray、mock、Android 公共 Download 保存和旧权限要求继续由 JS 兼容入口提供。

uni-app x

将原插件根路径换为新 ID：

import { downloadOrShareArrayBuffer, downloadOrShareByUrl }
  from '@/uni_modules/lf-file-share-uts'

六个基础 API 保留，新根入口增加五个 try*。options 仍可省略；share 为默认动作，download 为 save 别名。原生保存仍为沙盒，返回 isPublic:false。

Vapor 页面及其组件需要组合式 API，新 demo 使用 <script setup lang="uts">。使用独立 fixture 验证，现有 app-x 基座的其他页面由业务自行迁移。

共存与回退

新旧插件可同时安装，演示路由分别为 pages/file-share-uts/demo 和 pages/file-share/demo。
新插件没有旧包依赖，完成接入后可移除旧插件目录。
回退时恢复旧 import 即可；插件不会自动替换旧包调用。

Demo 与验证状态

新 demo 路由为 pages/file-share-uts/demo，旧路由 pages/file-share/demo 保留。展示销售报表、大 XLSX、BMP 大图、BIN、CSV、PDF、TXT、在线 PDF 和本地文本，共 18 个保存 / 分享操作。

bash scripts/sync-uni-modules.sh --plugin lf-file-share-uts --target both
node --test uniapp-Plugin/uni_modules/lf-file-share-uts/tests/*.test.mjs
node uniapp-Plugin/uni_modules/lf-file-share-uts/tests/fixture-projects.mjs

版权与授权

显式 JS 兼容实现复制自旧 SDK，保留原 MIT 版权及许可，见 LICENSE。新 UTS 实现的商业销售授权在正式上架前确定。复制代码的既有许可保持有效，不因新市场分类而更改。