简体中文
除了web,在App和小程序上都有访问文件系统的能力。
本文介绍uni-app x在app上的文件系统,列出文件系统包括的内容以及框架已经使用了哪些目录和文件。
注意:DCloud-
、DCloud_
、uni-
、uni_
开头的目录和文件是保留目录。开发者自用的文件目录需避免使用这些前缀。
开发者可以通过API uni.getFileSystemManager获取到文件系统管理器,进一步对文件目录进行增删改查。
const fs = uni.getFileSystemManager()
文件主要分两大类,代码包和本地磁盘文件:
uni.env.SANDBOX_PATH
):手机应用的沙盒目录,其中包括缓存文件目录和用户文件目录。在文件管理器中可看到。
uni.env.CACHE_PATH
):手机运行过程中框架保存缓存文件的目录(cache),系统空间不足时会被自动清理掉
uni.env.USER_DATA_PATH
):提供给开发者操作的本地文件目录(files)uni.env.ANDROID_INTERNAL_SANDBOX_PATH
):存放框架的网络缓存(如网络图片、视频、web-view的缓存)、storage。uts插件开发
在uts插件开发中调用系统 API 时可能需要平台相关的绝对路径,可以通过以下方式进行转换:
代码包文件,是源码工程中的静态资源文件,由编译器打包到发行包(如apk)中。全平台都如此。
uni-app x的应用在安装后,代码包文件有4个目录:
这些目录的来源和作用,详见
assets目录下文件有随机数的存在,很难使用FileSystemManager访问;hybrid下的文件用于web-view组件。
所以通过FileSystemManager访问较多的是static目录。
FileSystemManager访问代码包文件时,直接写文件路径,如:/static/uni.png、/uni_modules/xxx/static/clear.png。
示例
假设static目录下有如下文件:"/static/list-mock/mock.json",要copy到沙盒的files目录(该目录的介绍详见下一章节),可使用如下代码:
let fileManager = uni.getFileSystemManager()
fileManager.copyFile({
srcPath: "/static/list-mock/mock.json",
destPath: `${uni.env.USER_DATA_PATH}/mock.json`,
success: function (res : FileManagerSuccessResult) {
console.log('success', res)
},
fail: function (res : UniError) {
console.log('fail', res)
},
complete: function (res : any) {
console.log("complete", res)
}
} as CopyFileOptions)
注意:代码包文件只读,无法动态修改或删除。修改代码包文件一般会copy到沙盒目录后再修改。
真机运行注意
App端真机运行期间会做特殊处理,将代码包文件同步到应用沙盒目录
下的特定目录:
本地磁盘文件分沙盒内和沙盒外。
沙盒内是指应用安装到设备(通常指手机)后,系统会提供一块独立的文件存储区域。以应用维度隔离,即在同一台设备,不同应用间的本地磁盘文件不能直接相互访问。
而沙盒目录,又分内置和外置。外置可以在Android手机自带的系统文件管理器里看到,并且用户可以改动。内置的保护级别更高,无法在系统文件管理器中看到。
本地磁盘文件路径格式为:
{{协议名}}://文件路径
App端,协议名为"unifile",不应该直接拼写协议名路径访问本地磁盘文件,推荐使用uni.env中的目录常量获取本地磁盘文件目录的路径。
通过uni.env的目录常量访问本地磁盘文件
uni-app x提供了一批uni.env常量,来指定不同的可访问目录。
以下示例为在用户文件目录
下写入hello.txt文件:
const fs = uni.getFileSystemManager();
fs.writeFile({
filePath: `${uni.env.USER_DATA_PATH}/hello.txt`,
data: 'hello uni-app x!',
encoding: 'utf-8'
} as WriteFileOptions);
目录常量名称:uni.env.SANDBOX_PATH
App端专有目录,为应用沙盒根目录,其下包含了缓存文件目录
和用户文件目录
。此目录在不同平台差异较大,不建议直接使用此目录,需开发者根据平台特性谨慎操作。
实际保存的目录在不同平台存在差异:
缓存文件目录
,其下的files目录为用户文件目录
本目录可以在Android系统的文件管理器中看到。用户在文件管理器中可以查阅删改。手机被root后的沙盒机制也会失效,可以被其他app操作。
目录常量名称:uni.env.CACHE_PATH
缓存文件目录,保存应用运行过程中产生的缓存文件。操作系统或小程序宿主会在存储空间不足时清除缓存文件,因此不要在此目录中保存应用的关键业务数据文件。
实际保存的目录在不同平台存在差异:
uni-app x的部分内置API会产生临时文件会放置在本cache目录,如:
推荐:在调用上述API使用完毕临时文件后,就调用 uni.getFileSystemManager
的API把临时文件删掉。
从HBuilderX 3.99起,重新约定了缓存目录的使用规范。
在uni.env.CACHE_PATH
目录下,uni官方使用了如下目录,请开发者避免使用uni-开头的目录:
目录常量名称:uni.env.USER_DATA_PATH
App端和小程序提供了用户文件目录,用于开发者在应用运行期读写文件,此目录不会被操作系统自动清除,由开发者自由管理。
实际保存的目录在不同平台存在差异:
目录常量名称:uni.env.ANDROID_INTERNAL_SANDBOX_PATH
该目录无法在手机自带的文件管理器中查看,用户无法修改。除非手机被root。
uni-app x框架的一些内置组件和API会涉及缓存文件,存放到本目录,如:
FileSystemManager目前对内置应用沙盒目录为只读。如需写入,需开发uts插件。
FileSystemManager暂不支持访问沙盒外目录。如有相关需求目前需开发uts插件。
为了有更好的兼容性,建议处理文件路径时按大小写敏感原则处理