文件系统 - Files
> Stability: 2 - Stable
files模块提供了一些常见的文件处理，包括文件读写、移动、复制、删掉等。
一次性的文件读写可以直接使用`files.read()`, `files.write()`, `files.append()`等方便的函数，但如果需要频繁读写或随机读写，则使用`open()`函数打开一个文件对象来操作文件，并在操作完毕后调用`close()`函数关闭文件。
# 判断是否是文件 |isFile
| 函数名 | 返回值 | 备注 |
| -------------- | -------- | ------------------------ |
| files.isFile() | 布尔型 | 返回路径path是否是文件。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
log(files.isDir("/sdcard/文件夹/")); //返回false
log(files.isDir("/sdcard/文件.txt")); //返回true
```
# 判断是否是文件夹 |isDir
| 函数名 | 返回值 | 备注 |
| ------------- | -------- | -------------------------- |
| files.isDir() | 布尔型 | 返回路径path是否是文件夹。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
log(files.isDir("/sdcard/文件夹/")); //返回true
log(files.isDir("/sdcard/文件.txt")); //返回false
```
# 文件夹是否为空 |isEmptyDir
| 函数名 | 返回值 | 备注 |
| ------------------ | -------- | ------------------------------ |
| files.isEmptyDir() | 布尔型 | 返回文件夹path是否为空文件夹。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.isEmptyDir("/sdcard/文件夹/") //false true
```
# 文件路径合并 |join
| 函数名 | 返回值 | 备注 |
| ------------ | -------- | -------------------- |
| files.join() | 字符串 | 连接两个路径并返回， |
| **参数名** | **类型** | |
| parent | 字符串 | 父目录路径 |
| child | 字符串 | 子路径 |
```javascript
files.join("/sdcard/", "1.txt") //返回"/sdcard/1.txt"。
```
# 创建文件夹 |create
| 函数名 | 返回值 | 备注 |
| -------------- | -------- | ---------------------------------------- |
| files.create() | 布尔型 | 创建一个文件或文件夹并返回是否创建成功。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.create("/sdcard/新文件夹/");
```
# 创建文件 |createWithDirs
| 函数名 | 返回值 | 备注 |
| ---------------------- | -------- | ---------------------------------------- |
| files.createWithDirs() | 布尔型 | 创建一个文件或文件夹并返回是否创建成功。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.createWithDirs("/sdcard/新文件夹/新文件夹/新文件夹/1.txt");
如果文件所在文件夹不存在，则先创建他所在的一系列文件夹。
```
# 文件是否存在 |exists
| 函数名 | 返回值 | 备注 |
| -------------- | -------- | -------------------------------- |
| files.exists() | 布尔型 | 返回在路径path处的文件是否存在。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.exists()("/sdcard/新文件夹/1.txt");
```
# 文件是否存在W |ensureDir
| 函数名 | 返回值 | 备注 |
| ----------------- | -------- | ------------------------------ |
| files.ensureDir() | | 确保路径path所在的文件夹存在。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
例如对于路径"/sdcard/Download/ABC/1.txt"，如果/Download/文件夹不存在，则会先创建Download，再创建ABC文件夹。
如果该路径所在文件夹不存在，则创建该文件夹。
```
# 读取文本文件 |read
| 函数名 | 返回值 | 备注 |
| ------------ | -------- | ---------------------------------- |
| files.read() | 字符串 | 读取文本文件path的所有内容并返回。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
| encoding | 字符串 | 字符编码，可选，默认为utf-8 |
```javascript
log(files.read("/sdcard/1.txt"));
如果文件不存在，则抛出`FileNotFoundException`。
```
# 读取文本文件(字节集) |readBytes
| 函数名 | 返回值 | 备注 |
| ----------------- | -------- | ------------------------------------------ |
| files.readBytes() | 字节集 | 读取文件path的所有内容并返回一个字节数组。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
> 注意，该数组是Java的数组，不具有JavaScript数组的forEach, slice等函数。
```javascript
var data = files.readBytes("/sdcard/1.png");
var sb = new java.lang.StringBuilder();
for(var i = 0; i < data.length; i++){
sb.append(data[i].toString(16));
}
log(sb.toString());
如果文件不存在，则抛出`FileNotFoundException`。
```
# 写入文件 |write
| 函数名 | 返回值 | 备注 |
| ------------- | -------- | --------------------------- |
| files.write() | | 把text写入到文件path中。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
| text | 字符串 | 要写入的文本内容 |
| encoding | 字符串 | 字符编码，可选，默认为utf-8 |
```javascript
var text = "文件内容";
//写入文件
files.write("/sdcard/1.txt", text);
//用其他应用查看文件js
app.viewFile("/sdcard/1.txt");
如果文件存在则覆盖，不存在则创建。
```
# 写入文件(字节集) |writeBytes
| 函数名 | 返回值 | 备注 |
| ------------------ | -------- | ---------------------------- |
| files.writeBytes() | | 把bytes写入到文件path中。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
| bytes | 字节集 | 字节数组，要写入的二进制数据 |
```javascript
files.writeBytes("/sdcard/1.png",files.readBytes("/sdcard/2.png"))
如果文件存在则覆盖，不存在则创建。
```
# 写入文件尾 |append
| 函数名 | 返回值 | 备注 |
| -------------- | -------- | ---------------------------- |
| files.append() | | 把text追加到文件path的末尾。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
| text | 字符串 | 要写入的文本内容 |
| encoding | 字符串 | 字符编码，可选，默认为utf-8 |
```javascript
var text = "追加的文件内容";
files.append("/sdcard/1.txt", text);
files.append("/sdcard/1.txt", text);
//用其他应用查看文件
app.viewFile("/sdcard/1.txt");
如果文件不存在则创建。
```
# 写入文件尾(字节集) |appendBytes
| 函数名 | 返回值 | 备注 |
| ------------------- | -------- | ----------------------------- |
| files.appendBytes() | | 把bytes追加到文件path的末尾。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
| bytes | 字节集 | 字节数组，要写入的二进制数据 |
```javascript
files.appendBytes("/sdcard/1.dex", files.readBytes("/sdcard/2.dex"));
如果文件不存在则创建。
```
# 复制文件 |copy
| 函数名 | 返回值 | 备注 |
| ------------ | -------- | ---------------------------- |
| files.copy() | 布尔型 | 复制文件，返回是否复制成功。 |
| **参数名** | **类型** | |
| fromPath | 字符串 | 要复制的原文件路径 |
| toPath | 字符串 | 复制到的文件路径 |
```javascript
files.copy("/sdcard/1.txt", "/sdcard/Download/1.txt")
```
# 移动文件 |move
| 函数名 | 返回值 | 备注 |
| ------------ | -------- | ---------------------------- |
| files.move() | 布尔型 | 移动文件，返回是否移动成功。 |
| **参数名** | **类型** | |
| fromPath | 字符串 | 要移动的原文件路径 |
| toPath | 字符串 | 移动到的文件路径 |
```javascript
files.move("/sdcard/1.txt", "/sdcard/Download/1.txt") //会把1.txt文件从sd卡根目录移动到Download文件夹。
```
# 重命名文件 |rename
| 函数名 | 返回值 | 备注 |
| -------------- | -------- | ---------------------------------- |
| files.rename() | 布尔型 | 重命名文件，并返回是否重命名成功。 |
| **参数名** | **类型** | |
| path | 字符串 | 要重命名的原文件路径 |
| newName | 字符串 | 要重命名的新文件名 |
```javascript
files.rename("/sdcard/1.txt", "2.txt")
```
# 重命名文件(不含拓展名) |renameWithoutExtension
| 函数名 | 返回值 | 备注 |
| ------------------------------ | -------- | ------------------------------------------------ |
| files.renameWithoutExtension() | 布尔型 | 重命名文件，不包含拓展名，并返回是否重命名成功。 |
| **参数名** | **类型** | |
| path | 字符串 | 要重命名的原文件路径 |
| newName | 字符串 | 要重命名的新文件名 |
```javascript
files.rename("/sdcard/1.txt", "2") //会把"1.txt"重命名为"2.txt"。
```
# 获取文件名 |getName
| 函数名 | 返回值 | 备注 |
| --------------- | -------- | ------------------ |
| files.getName() | 字符串 | 返回文件的文件名。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.getName("/sdcard/1.txt") //返回"1.txt"。
```
# 获取文件名(不含拓展名) |getNameWithoutExtension
| 函数名 | 返回值 | 备注 |
| ------------------------------- | -------- | ------------------------------ |
| files.getNameWithoutExtension() | 字符串 | 返回不含拓展名的文件的文件名。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.getName("/sdcard/1.txt") //返回"1"。
```
# 获取文件拓展名 |getExtension
| 函数名 | 返回值 | 备注 |
| -------------------- | -------- | ------------------ |
| files.getExtension() | 字符串 | 返回文件的拓展名。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.getExtension("/sdcard/1.txt") //返回"txt"。
```
# 删除文件 |remove
| 函数名 | 返回值 | 备注 |
| -------------- | -------- | ------------------------------------------ |
| files.remove() | 布尔型 | 删除文件或**空文件夹**，返回是否删除成功。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.remove("/sdcard/1.txt")
```
# 删除文件夹 |removeDir
| 函数名 | 返回值 | 备注 |
| ----------------- | -------- | ---------- |
| files.removeDir() | 布尔型 | 删除文件夹 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
```javascript
files.removeDir("/sdcard/新文件夹")
如果文件夹不为空，则删除该文件夹的所有内容再删除该文件夹，返回是否全部删除成功。
```
# 获取SD卡路径 |getSdcardPath
| 函数名 | 返回值 | 备注 |
| --------------------- | ------ | -------------------------------------- |
| files.getSdcardPath() | 字符串 | 返回SD卡路径。所谓SD卡，即外部存储器。 |
# 获取脚本路径 |cwd
| 函数名 | 返回值 | 备注 |
| ----------- | ------ | ------------------------------- |
| files.cwd() | 字符串 | 返回脚本的"当前工作文件夹路径。 |
```javascript
例如，对于脚本文件"/sdcard/脚本/1.js"运行`files.cwd()`返回"/sdcard/脚本/"。
该路径指的是，如果脚本本身为脚本文件，则返回这个脚本文件所在目录；否则返回`null`获取其他设定路径。
```
# 获取文件绝对路径 |path
| 函数名 | 返回值 | 备注 |
| ------------ | -------- | ---------------------------- |
| files.path() | 字符串 | 返回相对路径对应的绝对路径。 |
| **参数名** | **类型** | |
| relativePath | 字符串 | 相对路径 |
```javascript
例如`files.path("./1.png")`，如果运行这个语句的脚本位于文件夹"/sdcard/脚本/"中，则返回`"/sdcard/脚本/1.png"`。
```
# 获取目录下文件 |listDir
| 函数名 | 返回值 | 备注 |
| --------------- | -------- | ------------------------------------------------------------ |
| files.listDir() | | 列出文件夹path下的满足条件的文件和文件夹的名称的数组。 |
| **参数名** | **类型** | |
| path | 字符串 | 路径 |
| filter | Function | 过滤函数，可空。接收一个`字符串`参数（文件名），返回一个`布尔`值。 |
```javascript
列出sdcard目录下所有文件和文件夹
var arr = files.listDir("/sdcard/");
log(arr);
列出脚本目录下所有js脚本文件
var dir = "/sdcard/脚本/";
var jsFiles = files.listDir(dir, function(name){
return name.endsWith(".js") && files.isFile(files.join(dir, name));
});
log(jsFiles);
如果不加filter参数，则返回所有文件和文件夹。
```
# 打开文件 |open
| 函数名 | 返回值 | 备注 |
| ---------- | -------- | ------------------------------- |
| open() | 字符串 | 打开一个文件。 |
| **参数名** | **类型** | |
| path | 字符串 | 文件路径，例如"/sdcard/1.txt"。 |
| mode | 字符串 | 文件打开模式 |
| encoding | 字符串 | 字符编码。 |
| bufferSize | 整数型 | 文件读写的缓冲区大小。 |
```javascript
文件打开模式，包括:
"r": 只读文本模式。该模式下只能对文件执行**文本**读取操作。
"w": 只写文本模式。该模式下只能对文件执行**文本**覆盖写入操作。
"a": 附加文本模式。该模式下将会把写入的文本附加到文件末尾。
"rw": 随机读写文本模式。该模式下将会把写入的文本附加到文件末尾。
目前暂不支持二进制模式，随机读写模式。
根据打开模式返回不同的文件对象。包括：
"r": 返回一个ReadableTextFile对象。
"w", "a": 返回一个WritableTextFile对象。
对于"w"模式，如果文件并不存在，则会创建一个，已存在则会清空该文件内容；其他模式文件不存在会抛出FileNotFoundException。
```
# 可读文件对象 |ReadableTextFile
> ReadableTextFile
## 取文件返回剩余内容 |read
| 函数名 | 返回值 | 备注 |
| ----------------------- | ------ | ------------------------ |
| ReadableTextFile.read() | 字符串 | 返回该文件剩余的所有内容 |
## 读取该文件最长字符串 |read
| 函数名 | 返回值 | 备注 |
| ----------------------- | -------- | ---------------------------------------------- |
| ReadableTextFile.read() | 字符串 | 读取该文件接下来最长为maxCount的字符串并返回。 |
| **参数名** | **类型** | |
| maxCount | 整数型 | 最大读取的字符数量 |
```javascript
即使文件剩余内容不足maxCount也不会出错。
```
## 读取一行并返回 |readline
| 函数名 | 返回值 | 备注 |
| --------------------------- | ------ | -------------------------------- |
| ReadableTextFile.readline() | 字符串 | 读取一行并返回（不包含换行符）。 |
## 读取剩余的所有行 |readlines
| 函数名 | 返回值 | 备注 |
| ---------------------------- | ------ | ---------------------------------------------------- |
| ReadableTextFile.readlines() | 字符串 | 读取剩余的所有行，并返回它们按顺序组成的字符串数组。 |
## 关闭该文件 |close
| 函数名 | 返回值 | 备注 |
| ------- | ------ | ---------------------------------------------- |
| close() | | 关闭该文件。**打开一个文件不再使用时务必关闭** |
# 可写文件对象 |PWritableTextFile
> PWritableTextFile
可写文件对象。
## 写入到文件中 |write
| 函数名 | 返回值 | 备注 |
| ------------------------- | -------- | ---------------------------- |
| PWritableTextFile.write() | | 把文本内容text写入到文件中。 |
| **参数名** | **类型** | |
| text | 字符串 | 文本 |
## 写入到文件中换行 |writeline
| 函数名 | 返回值 | 备注 |
| ----------------------------- | -------- | ---------------------------------------- |
| PWritableTextFile.writeline() | | 把文本line写入到文件中并写入一个换行符。 |
| **参数名** | **类型** | |
| text | 字符串 | 文本 |
## 写入到文件中(很多行) |writelines
| 函数名 | 返回值 | 备注 |
| ------------------------------ | -------- | ------------------------ |
| PWritableTextFile.writelines() | | 把很多行写入到文件中.... |
| **参数名** | **类型** | |
| lines | 字符串 | 字符串数组 |
## 缓冲区内容输出到文件中 |flush
| 函数名 | 返回值 | 备注 |
| ------------------------- | ------ | -------------------------- |
| PWritableTextFile.flush() | | 把缓冲区内容输出到文件中。 |
## 关闭文件 |close
| 函数名 | 返回值 | 备注 |
| ------------------------- | ------ | ---------------------------------------- |
| PWritableTextFile.close() | | 关闭文件。同时会被缓冲区内容输出到文件。 |
> **打开一个文件写入后，不再使用时务必关闭，否则文件可能会丢失**