更新记录

1.0.0（2026-09-22）

• 新增 U 盘和移动硬盘文件管理，可浏览文件和文件夹、读取内容、写入文本、创建文件夹、重命名和删除。
• 新增应用与 U 盘、移动硬盘之间的双向复制，可查看进度并在需要时取消。
• 新增目录授权记忆和存储连接状态查询；写入同名文件失败时保留原文件，避免误覆盖已有资料。
• 优化示例页面的打开体验、按钮布局和操作说明。
• 修复 Android 查询存储能力和选择目录时偶发失败的问题。
• 修复复制取消、释放授权和写入失败时可能留下未完成任务的问题。
• 修复部分平台无法正常返回“不支持”提示的问题。无需修改调用代码；Android 更新后需要重新制作并安装自定义基座或重新打包 App。
• 首版支持 Android 的 uni-app 和 uni-app x 项目，其他平台暂不支持。首次使用时，请在系统文件选择器中选择允许访问的目录。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

lizhao-usb-storage

lizhao-usb-storage 让 Android 应用可以在用户选择授权后，直接浏览、读取和写入 U 盘、移动硬盘中的文件。它适合现场资料交换、离线导入导出和移动备份，可同时用于 uni-app 与 uni-app x。

功能特色

• 文件管理：浏览文件和文件夹，查看文件大小与修改时间，创建文件夹、重命名和删除。
• 文件读写：读取或保存文本及其他文件内容，满足资料导入、数据导出等需求。
• 双向复制：将应用中的文件复制到 U 盘或移动硬盘，也可将外置存储中的文件复制到应用。
• 进度与取消：查看复制进度，按需中途取消。
• 记住授权：再次打开应用时可恢复仍有效的目录授权，减少重复选择。
• 连接状态：查询系统识别到的存储设备，接收连接状态变化通知。

适合哪些场景

首次使用时，需要在系统文件选择器中选择允许访问的文件夹；插件只操作用户明确授权的目录。

下载与导入

1. 在插件市场选择“使用 HBuilderX 导入插件”，导入到 uni-app 或 uni-app x 项目。
2. 保留完整的 uni_modules/lizhao-usb-storage 目录，不要修改插件目录名。
3. 在页面脚本中从插件根目录导入：

import {
  getCapabilities,
  pickStorageRoot,
  listEntries,
  writeTextFile,
  readTextFile
} from '@/uni_modules/lizhao-usb-storage'

完整示例位于插件目录的 example/ 下：

• uni-app：example/uniapp/index.vue
• uni-app x：example/uniappx/index.uvue

5 分钟跑通

先完成“查询能力 → 选择目录 → 文件操作”这三个步骤，再按业务需要添加复制、进度和状态监听。

1. 导入插件并查询能力

import {
  getCapabilities,
  pickStorageRoot,
  listEntries,
  writeTextFile,
  readTextFile
} from '@/uni_modules/lizhao-usb-storage'

getCapabilities({
  success: (res) => {
    console.log('USB 存储能力', res)
  },
  fail: (err) => {
    console.error('查询能力失败', err.errCode, err.errMsg)
  }
})

2. 让用户选择外置存储目录

let storageId = ''

pickStorageRoot({
  title: '请选择 U 盘或移动硬盘目录',
  success: (storage) => {
    storageId = storage.storageId
    console.log('已取得存储授权', storage.displayName)
  },
  fail: (err) => {
    console.error('选择目录失败', err.errCode, err.errMsg)
  }
})

用户取消选择会返回 9036005。目录授权失效、系统拒绝访问或存储设备断开时，请提示用户重新连接设备并选择可访问的文件夹。

3. 写入并读回文本

writeTextFile({
  storageId,
  path: '/lizhao-demo/hello.txt',
  text: '你好，USB 存储！',
  encoding: 'utf-8',
  createParents: true,
  success: () => {
    readTextFile({
      storageId,
      path: '/lizhao-demo/hello.txt',
      success: (res) => console.log('读回内容', res.text),
      fail: (err) => console.error('读取失败', err.errCode, err.errMsg)
    })
  },
  fail: (err) => console.error('写入失败', err.errCode, err.errMsg)
})

所有异步 API 均使用 success、fail、complete 回调。失败时不会调用 success；complete 最多调用一次。

接入方式选择

模块介绍

模块一：能力与授权

getCapabilities 只查询当前平台是否支持；pickStorageRoot 打开系统文件选择器，让使用者选择 U 盘或移动硬盘中的目录。选择成功后保存返回的 storageId，后续所有文件操作都使用它。

模块二：文件与目录

使用 listEntries 浏览目录，使用 statEntry 查看文件信息，使用 createDirectory、renameEntry 和 deleteEntry 完成整理。传入的路径只能是已授权目录内的相对路径，根目录不能删除。

模块三：文件读写

文本文件优先使用 readTextFile 和 writeTextFile；小型二进制文件使用 readFile 和 writeFile。写入同名文件时默认失败并保留原文件，避免误覆盖已有资料。

模块四：双向复制、进度与取消

copyToStorage 把应用内文件复制到 U 盘，copyFromStorage 把 U 盘文件复制到应用目录。复制开始会通过 onStart 返回 taskId，进度通过 onProgress 返回；用户点击取消时调用 cancelTask。

模块五：连接状态与资源释放

listStorages 可恢复仍有效的目录授权，listMountedVolumes 可查看系统识别到的存储设备；onStorageEvent 用于接收插拔变化。页面销毁或不再使用插件时调用 releaseResources。

常用参数

文件路径必须位于用户已选择并授权的目录内。不要传入完整系统地址、盘符路径、包含 .. 的越界路径或空文件名；违规返回 9036017。

文件与目录 API

二进制 readFile 面向小文件并受 maxBytes 限制。大文件请使用 copyFromStorage，避免把完整内容一次性放入 JavaScript 内存。

文件复制、进度与取消

复制开始后先触发 onStart，立即提供可取消的 taskId；随后通过 onProgress 报告进度，最终由 success 或 fail 结束。

let taskId = ''

copyToStorage({
  sourcePath: `${uni.env.USER_DATA_PATH}/export.zip`,
  storageId,
  targetPath: '/backup/export.zip',
  createParents: true,
  onStart: (res) => {
    taskId = res.taskId
  },
  : (progress) => {
    console.log(progress.taskId, progress.completedBytes, progress.totalBytes, progress.state)
  },
  success: () => console.log('复制完成'),
  fail: (err) => console.error('复制失败', err.errCode, err.errMsg)
})

// 用户点击取消按钮时调用
if (taskId) {
  cancelTask({ taskId })
}

copyFromStorage 用于从外置存储复制到应用可写的本地路径。每个 storageId 同时只允许一个活动写入任务；取消时会停止复制，并尝试清理本次新建且未完成的目标文件。对已完成、未知或已取消的 taskId 请求取消时，会返回明确错误。

覆盖策略

向外置存储写入或复制文件时，请使用默认的 overwrite: false。发现同名文件会返回错误并保留原文件，可更换目标文件名后重试。当前不支持覆盖外置存储中的文件，传入 overwrite: true 也会返回错误。

可用功能与连接状态

• getCapabilities 仅查询平台能力，不会自动申请权限。
• pickStorageRoot 打开系统文件选择器，取得并保存用户选择的目录授权。
• checkAllFilesAccessPermission 与 openAllFilesAccessSettings 用于查询或打开 Android “所有文件访问”设置；使用本插件读写已授权目录不需要开启此项。
• UsbStorageCapabilities.usbPermission 不能作为文件可读写的判断依据，文件访问以所选目录的授权结果为准。
• onStorageEvent / offStorageEvent 用于接收或停止接收存储连接变化通知。收到通知后请重新调用 listStorages 检查目录是否仍可访问，必要时重新选择目录。
• releaseStorage 撤销指定目录的授权；releaseResources 取消任务、停止接收通知并清理当前使用的资源。

支持平台

插件只能访问系统文件选择器中显示且已获授权的目录。能否识别 U 盘或移动硬盘取决于设备系统、磁盘格式和供电情况；部分设备只能选择盘内文件夹。插件不提供磁盘格式化或分区功能。

错误码

注意事项

1. 首次接入或升级插件后，请重新制作并安装 Android 自定义基座或重新打包 App。
2. 移动硬盘可能需要独立供电。设备已连接但文件选择器看不到目录时，先检查 OTG 转接、供电和系统文件管理器。
3. 即使设备已经连接，首次读写前仍需在系统文件选择器中选择允许访问的文件夹。
4. 存储设备断开或目录权限变化后，原目录可能无法访问；请重新连接并选择目录。

许可证

本插件遵循仓库许可证。