更新记录

0.1.0（2026-06-27） 下载此版本

初次提交

平台兼容性

uni-app x(5.0)

其他

laoqianjunzi-file

laoqianjunzi-file 是一个面向 uni-app x 的 UTS 文件能力插件，统一提供以下能力：

• 本地文件选择
• 本地文件上传
• 目录解析与目录遍历
• 文本文件读写
• 文件与目录的创建、复制、移动、删除
• 批量远程下载
• 压缩与解压
• 文件只读与隐藏状态控制

本插件以当前正式 API 为唯一文档入口，README 与示例页均不涉及旧插件、旧命名或兼容式调用说明。

适用平台

• Android
• iOS
• Harmony
• Web

要求环境：

• HBuilderX 5.07 及以上
• uni-app x 工程

能力总览

平台能力矩阵

describeCapabilities() 返回值说明

describeCapabilities() 会返回当前平台声明支持的能力标签：

当前各端的典型返回：

• Android：picker、upload、permission、archive、hidden、read-only、batch-download、public-storage
• iOS：picker、upload、permission、batch-download
• Harmony：picker、upload、permission、batch-download
• Web：picker、upload

安装与引入

将插件放入项目的 uni_modules 目录后，直接按模块路径引入：

import {
  describeCapabilities,
  requestFileAccess,
  resolveDirectory,
  selectLocalFiles,
  writeTextContent
} from '@/uni_modules/laoqianjunzi-file'

内置示例页

插件内已提供演示页：

• uni_modules/laoqianjunzi-file/pages/index.uvue

该页面演示了：

• 权限检查与能力读取
• 文件选择与结果展示
• 工作区目录创建
• 文本文件写入、追加、读取、列表刷新
• 文件复制、移动、删除
• 批量下载、上传、压缩、解压

快速开始

1. 检查平台能力与权限

import {
  describeCapabilities,
  requestFileAccess
} from '@/uni_modules/laoqianjunzi-file'

const capabilityResult = describeCapabilities()
console.log('capabilities', capabilityResult.capabilities)

requestFileAccess().then((permissionResult) => {
  console.log('permission', permissionResult)
})

2. 选择文件

import {
  selectLocalFiles,
  type LaoFileRecord
} from '@/uni_modules/laoqianjunzi-file'

selectLocalFiles({
  multiple: true,
  maxCount: 3,
  copyToCache: true,
  fileTypes: ['image', 'doc'],
  extensions: ['jpg', 'png', 'pdf'],
  success: (res) => {
    const files: LaoFileRecord[] = res.files
    console.log('picked files', files)
  },
  fail: (err) => {
    console.log('pick failed', err.errCode, err.errMsg)
  }
})

3. 创建工作区并写入文本

import {
  createEntry,
  resolveDirectory,
  writeTextContent
} from '@/uni_modules/laoqianjunzi-file'

resolveDirectory('sandbox-files').then((dirRes) => {
  if (!dirRes.success || dirRes.path == null) {
    return
  }
  const workspace = dirRes.path + '/laoqianjunzi-file-demo'
  createEntry(workspace, false).then((folderRes) => {
    if (!folderRes.success || folderRes.path == null) {
      return
    }
    const textPath = folderRes.path + '/note.txt'
    writeTextContent(textPath, 'hello uni-app x', false).then((writeRes) => {
      console.log('write result', writeRes)
    })
  })
})

4. 读取目录与文本

import {
  readDirectory,
  readTextContent
} from '@/uni_modules/laoqianjunzi-file'

readDirectory('/your/workspace', 'txt').then((listRes) => {
  console.log('txt files', listRes.files)
})

readTextContent('/your/workspace/note.txt').then((textRes) => {
  console.log('content', textRes.content)
})

5. 上传本地文件

import { uploadLocalFile } from '@/uni_modules/laoqianjunzi-file'

uploadLocalFile({
  url: 'https://httpbin.org/post',
  filePath: '/your/local/file.txt',
  name: 'file',
  formData: {
    scene: 'demo'
  } as UTSJSONObject,
  Update: (progress) => {
    console.log('upload progress', progress.progress)
  },
  success: (res) => {
    console.log('upload success', res.statusCode, res.data)
  },
  fail: (err) => {
    console.log('upload fail', err.errCode, err.errMsg)
  }
})

6. 批量下载

import {
  downloadRemoteFiles,
  resolveDirectory
} from '@/uni_modules/laoqianjunzi-file'

resolveDirectory('sandbox-cache').then((dirRes) => {
  if (!dirRes.success || dirRes.path == null) {
    return
  }
  downloadRemoteFiles(dirRes.path, [
    'https://www.w3.org/TR/PNG/iso_8859-1.txt'
  ]).then((downloadRes) => {
    console.log('download result', downloadRes.savedPaths)
  })
})

API 说明

类型定义

FilePickerGroup

可选值：

• all
• image
• video
• audio
• doc
• text
• archive
• file

FileSystemBucket

可选值：

• external-cache
• external-files
• sandbox-cache
• sandbox-files
• public-root

EntryKind

可选值：

• any
• file
• directory

LaoFileRecord

文件选择

selectLocalFiles(options)

参数

成功结果

success 回调中最重要的结果字段是：

• files：统一后的 LaoFileRecord[]

实际业务中建议只以 files 为准继续后续上传、复制、读写等流程。

上传

uploadLocalFile(options)

参数

成功结果

权限与能力

requestFileAccess()

返回 Promise<PermissionResult>。

说明：

• Android 会执行真实运行时权限申请
• iOS 与 Harmony 以当前沙箱访问能力为主
• Web 直接返回可用状态，不涉及原生存储授权

describeCapabilities()

同步返回 CapabilityResult，用于判断当前平台应展示哪些入口。

目录与文件系统

resolveDirectory(bucket)

返回 Promise<PathResult>，用于拿到当前平台的基础目录。

各目录桶说明

createEntry(targetPath, createFile?)

• createFile = false：创建目录
• createFile = true：创建文件

返回 Promise<PathResult>。

copyEntry(sourcePath, targetPath, overwrite?)

复制文件或目录，返回 Promise<PathResult>。

moveEntry(sourcePath, targetPath, overwrite?)

移动文件或目录，返回 Promise<PathResult>。

deleteEntry(targetPath)

删除文件或目录，返回 Promise<OperationResult>。

existsEntry(targetPath, kind?)

检查目标是否存在，返回 Promise<ExistsResult>。

measureEntry(targetPath)

读取文件或目录大小，返回 Promise<SizeResult>。

readDirectory(targetPath, suffix?)

读取目录第一层子项，返回 Promise<FileListResult>。

说明：

• suffix 可传 txt、jpg、zip 等后缀
• 传空字符串表示不过滤
• 目录项会一并返回，便于做文件浏览与继续下钻

文本读写

readTextContent(targetPath)

返回 Promise<TextResult>。

补充说明：

• App 端读取本地文本文件
• Web 端读取可访问的文本 URL 或同源资源

writeTextContent(targetPath, content, append?)

返回 Promise<PathResult>。

• append = false：覆盖写入
• append = true：追加写入

下载、压缩与解压

downloadRemoteFiles(saveDirectory, urls)

批量下载远程文件，返回 Promise<DownloadResult>。

结果结构：

compressDirectory(directoryPath, archivePath, password?)

压缩目录，返回 Promise<PathResult>。

compressEntries(entryPaths, archivePath, password?)

压缩指定文件或目录集合，返回 Promise<PathResult>。

extractArchive(archivePath, targetDirectory, password?)

解压归档文件，返回 Promise<PathResult>。

说明：

• Android 支持压缩、解压、密码参数
• iOS、Harmony、Web 当前会返回 9801020

状态控制

updateReadOnlyState(targetPath, readOnly?, recursive?)

设置只读状态，返回 Promise<OperationResult>。

说明：

• Android 支持
• iOS、Harmony、Web 当前不支持

updateHiddenState(targetPath, hidden?)

设置隐藏状态，返回 Promise<OperationResult>。

说明：

• Android 支持
• iOS、Harmony、Web 当前不支持

错误码

实战建议

• 业务代码请优先调用 describeCapabilities() 决定 UI 展示与按钮可用性
• 文件选择后请直接基于 files 字段继续流程，不要依赖兼容字段
• 需要跨端一致行为时，优先使用 sandbox-cache 与 sandbox-files
• Web 端更适合作为选择、上传、远程文本读取的轻量入口，不建议假设其拥有本地文件系统能力
• 批量下载、压缩、解压建议先落到工作区目录，再由业务决定是否继续复制或上传

示例页联调建议

若你想快速验证插件能力，建议直接打开：

• uni_modules/laoqianjunzi-file/pages/index.uvue

建议验证顺序：

1. 先点“读取能力”和“检查权限”确认平台声明
2. 再执行“准备工作区”“写入文本”“读取目录”验证基础文件系统
3. 最后执行“上传”“下载”“压缩”“解压”验证进阶链路