file-system-spec.md 9.2 KB
Newer Older
W
x  
wanganxp 已提交
1 2
# 文件系统

D
DCloud_LXH 已提交
3 4
>  [uni.env 参见](./env.md)

DCloud_Heavensoft's avatar
DCloud_Heavensoft 已提交
5 6 7
除了web,在App和小程序上都有访问文件系统的能力。

本文介绍uni-app x在app上的文件系统,列出文件系统包括的内容以及框架已经使用了哪些目录和文件。
W
wanganxp 已提交
8 9 10

注意:`DCloud-``DCloud_``uni-``uni_`开头的目录和文件是保留目录。开发者自用的文件目录需避免使用这些前缀。

D
DCloud_LXH 已提交
11
开发者可以通过API [uni.getFileSystemManager](get-file-system-manager.md)获取到文件系统管理器,进一步对文件目录进行增删改查。
W
x  
wanganxp 已提交
12 13 14 15
```uts
const fs = uni.getFileSystemManager()
```

W
x  
wanganxp 已提交
16
文件主要分两大类,代码包和本地磁盘文件:
W
x  
wanganxp 已提交
17 18 19 20 21 22 23 24 25 26 27 28
- 代码包文件:指 uni-app x 项目目录中添加的文件,比如static目录下的文件。Android发行后存放在assets目录下。只读。
	+ assets
	+ hybrid
	+ static
	+ uni_modules
- 本地磁盘文件:指应用在手机端运行时可访问的磁盘文件。又分以下目录:
	+ 应用外置沙盒目录(`uni.env.SANDBOX_PATH`):手机应用的沙盒目录,其中包括缓存文件目录和用户文件目录。在文件管理器中可看到。
		* 缓存文件目录(`uni.env.CACHE_PATH`):手机运行过程中框架保存缓存文件的目录(cache),系统空间不足时会被自动清理掉
			- uni-download :下载
			- uni-media :拍照、相册选择
			- uni-snapshot :App dom截图
			- uni-crash :App崩溃日志
D
DCloud_LXH 已提交
29
		* 用户文件目录(`uni.env.USER_DATA_PATH`):提供给开发者操作的本地文件目录(files)
W
x  
wanganxp 已提交
30 31 32
	+ 应用内置沙盒目录(`uni.env.ANDROID_INTERNAL_SANDBOX_PATH`):存放框架的网络缓存(如网络图片、视频、web-view的缓存)、storage。
	+ 沙盒外目录

33 34 35 36 37 38 39
**uts插件开发**  
在uts插件开发中调用系统 API 时可能需要平台相关的绝对路径,可以通过以下方式进行转换:  
- app-android平台  
  [UTSAndroid.convert2AbsFullPath](../uts/utsandroid.md#convert2absfullpath)  
- app-ios平台  
  [UTSiOS.convert2AbsFullPath](../uts/utsios.md#convert2absfullpath)  

W
wanganxp 已提交
40
## 代码包文件@package
W
x  
wanganxp 已提交
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77

代码包文件,是源码工程中的静态资源文件,由编译器打包到发行包(如apk)中。全平台都如此。

uni-app x的应用在安装后,代码包文件有4个目录:
- assets
- hybrid
- static
- uni_modules

这些目录的来源和作用,[详见](../compiler/README.md#static)

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目录(该目录的介绍详见下一章节),可使用如下代码:
```ts
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)
```

W
wanganxp 已提交
78
> 注意:代码包文件只读,无法动态修改或删除。修改代码包文件一般会copy到沙盒目录后再修改。
W
x  
wanganxp 已提交
79 80 81

**真机运行注意**

D
DCloud_LXH 已提交
82 83
App端真机运行期间会做特殊处理,将代码包文件同步到`应用沙盒目录`下的特定目录:
- Android平台
W
x  
wanganxp 已提交
84
	保存在应用专属存储空间的外置存储空间根目录下的apps目录,通常为“/sdcard/Android/data/%应用包名%/apps/%应用AppID%/www/”
D
DCloud_LXH 已提交
85
- iOS平台
W
x  
wanganxp 已提交
86 87 88
	保存在应用沙盒目录下的Documents/uni-app-x目录,通常为“/%应用沙盒目录%/Documents/uni-app-x/apps/%应用AppID%/www/”


W
wanganxp 已提交
89
## 本地磁盘文件@disk
W
x  
wanganxp 已提交
90 91
本地磁盘文件分沙盒内和沙盒外。

D
DCloud_LXH 已提交
92
沙盒内是指应用安装到设备(通常指手机)后,系统会提供一块独立的文件存储区域。以应用维度隔离,即在同一台设备,不同应用间的本地磁盘文件不能直接相互访问。
W
x  
wanganxp 已提交
93 94 95

而沙盒目录,又分内置和外置。外置可以在Android手机自带的系统文件管理器里看到,并且用户可以改动。内置的保护级别更高,无法在系统文件管理器中看到。

D
DCloud_LXH 已提交
96
本地磁盘文件路径格式为:
W
x  
wanganxp 已提交
97
```
D
DCloud_LXH 已提交
98
{{协议名}}://文件路径
W
x  
wanganxp 已提交
99
```
D
DCloud_LXH 已提交
100
> App端,协议名为"unifile",不应该直接拼写协议名路径访问本地磁盘文件,推荐使用uni.env中的目录常量获取本地磁盘文件目录的路径。
W
x  
wanganxp 已提交
101

D
DCloud_LXH 已提交
102
**通过uni.env的目录常量访问本地磁盘文件**
W
x  
wanganxp 已提交
103 104 105

uni-app x提供了一批uni.env常量,来指定不同的可访问目录。

D
DCloud_LXH 已提交
106
以下示例为在`用户文件目录`下写入hello.txt文件:
W
x  
wanganxp 已提交
107 108 109 110 111 112 113 114 115 116
```ts
const fs = uni.getFileSystemManager();
fs.writeFile({
	filePath: `${uni.env.USER_DATA_PATH}/hello.txt`,
	data: 'hello uni-app x!',
	encoding: 'utf-8'
} as WriteFileOptions);
```


W
wanganxp 已提交
117
### 外置应用沙盒目录@sandbox
W
x  
wanganxp 已提交
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
目录常量名称:`uni.env.SANDBOX_PATH`

App端专有目录,为应用沙盒根目录,其下包含了`缓存文件目录``用户文件目录`。此目录在不同平台差异较大,不建议直接使用此目录,需开发者根据平台特性谨慎操作。

实际保存的目录在不同平台存在差异:
- Android平台
	应用专属存储空间的外置存储空间根目录,通常为“/Android/data/%应用包名%/”,其下的cache目录为`缓存文件目录`,其下的files目录为`用户文件目录`
- iOS平台
	应用沙盒虚拟目录,其下包括Document、Library、tmp目录,此目录只可读,不可创建其它目录

本目录可以在Android系统的文件管理器中看到。用户在文件管理器中可以查阅删改。手机被root后的沙盒机制也会失效,可以被其他app操作。

#### 缓存文件目录cache@cache
目录常量名称:`uni.env.CACHE_PATH`

D
DCloud_LXH 已提交
133
缓存文件目录,保存应用运行过程中产生的缓存文件。操作系统或小程序宿主会在存储空间不足时清除缓存文件,因此不要在此目录中保存应用的关键业务数据文件。
W
x  
wanganxp 已提交
134 135

实际保存的目录在不同平台存在差异:
D
DCloud_LXH 已提交
136 137 138 139
- Android平台
	应用专属存储空间的外置存储空间根目录下的cache目录,通常为“/Android/data/%应用包名%/cache/”
- iOS平台
	应用沙盒目录下的Library/Caches目录
W
x  
wanganxp 已提交
140 141 142

uni-app x的部分内置API会产生临时文件会放置在本cache目录,如:
- uni.downloadFile下载的文件
143 144 145
- uni.chooseImage、uni.chooseVideo拍摄或选择的相册文件
- uni.compressImage、uni.compressVideo压缩后的文件
- uni.getImageInfo网络图片下载到本地的文件
W
x  
wanganxp 已提交
146 147 148 149 150 151 152 153 154
<!-- - 录音的文件 -->
- dom element的截图API

推荐:在调用上述API使用完毕临时文件后,就调用 `uni.getFileSystemManager` 的API把临时文件删掉。

从HBuilderX 3.99起,重新约定了缓存目录的使用规范。

`uni.env.CACHE_PATH`目录下,uni官方使用了如下目录,请开发者避免使用uni-开头的目录:
- uni-download // uni.downloadFile的默认下载地址 (在HBuilderX 3.98时曾使用目录uniDownloads,从3.99起调整为uni-download)
155
- uni-media // uni.chooseImage、uni.chooseVideo拍摄或选择的相册文件,uni.compressImage、uni.compressVideo压缩后的文件,uni.getImageInfo网络图片下载到本地的文件
W
x  
wanganxp 已提交
156 157 158 159 160
- uni-snapshot // element takeSnapShot截图APi存储的路径
- uni-crash //存放崩溃日志
	* java //java、kotlin层崩溃日志
	* c //c、so库崩溃日志

D
DCloud_LXH 已提交
161
#### 用户文件目录files@files
W
x  
wanganxp 已提交
162 163
目录常量名称:`uni.env.USER_DATA_PATH`

D
DCloud_LXH 已提交
164
App端和小程序提供了用户文件目录,用于开发者在应用运行期读写文件,此目录不会被操作系统自动清除,由开发者自由管理。
W
x  
wanganxp 已提交
165

D
DCloud_LXH 已提交
166 167 168 169 170
实际保存的目录在不同平台存在差异:
- Android平台
	应用专属存储空间的外置存储空间根目录下的files目录,通常为“/sdcard/Android/data/%应用包名%/files/”
- iOS平台
	应用沙盒目录下的Document目录
W
x  
wanganxp 已提交
171

W
wanganxp 已提交
172
### 内置应用沙盒目录@internalsandbox
W
x  
wanganxp 已提交
173 174 175 176 177 178

目录常量名称:`uni.env.ANDROID_INTERNAL_SANDBOX_PATH`

该目录无法在手机自带的文件管理器中查看,用户无法修改。除非手机被root。

uni-app x框架的一些内置组件和API会涉及缓存文件,存放到本目录,如:
W
x  
wanganxp 已提交
179
- image/video组件的网络图片视频缓存
W
x  
wanganxp 已提交
180
- web-view组件的缓存
W
x  
wanganxp 已提交
181 182

FileSystemManager目前对内置应用沙盒目录为只读。如需写入,需开发uts插件。
W
x  
wanganxp 已提交
183 184

### 沙盒外目录
DCloud_Heavensoft's avatar
DCloud_Heavensoft 已提交
185
FileSystemManager暂不支持访问沙盒外目录。如有相关需求目前需开发uts插件。
DCloud-yyl's avatar
DCloud-yyl 已提交
186 187

## 常见问题  
DCloud-yyl's avatar
DCloud-yyl 已提交
188
### 文件路径中字母大小写敏感问题@casesensitive  
DCloud-yyl's avatar
DCloud-yyl 已提交
189
- Android平台  
DCloud-yyl's avatar
DCloud-yyl 已提交
190 191
	+ 本地磁盘文件路径中字母大小写不敏感,真机运行时会将应用资源同步到设备的SD卡中,此时路径中字母大小写不敏感  
	+ 代码包文件中的文件打包后到apk中后,由于Android系统的要求是大小写敏感,因此发布为后应用资源路径中的字母大小写敏感  
DCloud-yyl's avatar
DCloud-yyl 已提交
192
- iOS平台  
DCloud-yyl's avatar
DCloud-yyl 已提交
193 194
	+ iOS真机文件路径中字母大小写敏感  
	+ iOS模拟器文件路径中字母大小写不敏感  
DCloud-yyl's avatar
DCloud-yyl 已提交
195

DCloud-yyl's avatar
DCloud-yyl 已提交
196
> 为了有更好的兼容性,建议处理文件路径时按大小写敏感原则处理