在自动化脚本中进行文件相关操作

在移动端自动化开发中，文件操作是不可或缺的基础能力——无论是读写配置文件、存储日志，还是处理图片等资源文件，都绕不开对文件系统的管理。本文将系统性地梳理冰狐平台中文件相关操作的核心方法、使用场景与注意事项。

一、FileX 构造函数与路径体系

冰狐平台的文件操作入口是 FileX 构造函数。它接受一个 path 参数，支持三种路径形式：

这种设计兼顾了灵活性——既可以直接操作绝对路径，也可以简化代码中的路径书写，还能访问应用内置资源。创建 FileX 实例的方式如下：

// 全路径
var file = new FileX("/sdcard/logs/app.log");
// 相对路径（相对于外部存储根目录）
var file2 = new FileX("logs/app.log");
// 资源文件
var file3 = new FileX("asset:config.json");

二、文件与目录状态检查

在操作文件之前，通常需要先确认目标路径的类型和存在性。冰狐提供了以下几个基础判断方法：

• isFile()：返回 boolean，判断当前路径是否为文件。

• isDir()：返回 boolean，判断当前路径是否为目录。

• exists()：返回 boolean，判断文件或目录是否存在。

• size()：返回 integer，获取文件大小（字节数）。

• getModifyTime()：返回 integer，获取文件的最后修改时间戳。

这些方法可用于编写健壮的预处理逻辑。例如，在读取配置文件前，可以先检查文件是否存在，避免运行时异常：

var conf = new FileX("/sdcard/app/config.json");
if (conf.exists() && conf.isFile()) {
// 安全读取
} else {
// 初始化默认配置
}

此外，getName() 方法可以获取文件名，getPath() 方法可以获取当前对象的完整路径，在需要拼接或展示路径时非常实用。

三、目录操作

目录管理在日志归档、缓存清理等场景中频繁使用。冰狐提供了目录创建和遍历相关的方法：

• makeDirs()：创建文件夹（包括多级不存在的父目录），返回 boolean 表示是否成功。

• listFiles()：列出目录中的所有文件和子目录，返回一个字符串数组，每个元素为文件的全路径。

结合使用这两个方法，可以实现目录的初始化与内容扫描：

var dir = new FileX("/sdcard/app/cache/images");
if (!dir.exists()) {
dir.makeDirs();
}
var files = dir.listFiles();
for (var i = 0; i < files.length; i++) {
// 处理每个文件
}

四、文件删除与移动

冰狐提供了文件/目录的删除和移动能力：

• remove()：删除文件或文件夹。特别需要注意的是，如果目标为目录且非空，该方法会自动递归删除目录内的所有内容后再删除目录本身。这简化了清理操作，但使用时需格外谨慎，避免误删。

• moveTo(destFilePath)：将当前文件移动到目标路径。目标路径参数 destFilePath 为必填，且需要包含完整的文件名。

移动操作在文件重命名或归档场景中非常实用。例如：

var log = new FileX("/sdcard/app/logs/current.log");
var archive = "/sdcard/app/logs/archive/2026-08-06.log";
log.moveTo(archive);

五、文件读写操作

读写是文件操作的核心。冰狐提供了文本读取、字节读取、文本写入和追加写入四种方式。

1. 读取文件

• read(charset)：以字符串形式读取文件内容。charset 为选填参数，默认 utf-8。

• readBytes()：以字节数组（byte[]）形式读取文件内容，适用于图片、二进制文件等非文本数据。

var txt = new FileX("/sdcard/app/data.txt");
var content = txt.read(); // 默认 utf-8
var contentGBK = txt.read("gbk"); // 指定字符集

2. 写入文件

• write(content, charset)：将数据写入文件。content 可以是字符串或字节数组，charset 仅在 content 为字符串时有效，默认 utf-8。如果文件不存在则自动新建，路径不存在则会自动创建所有父目录。

• append(content, charset)：将数据追加到文件末尾，行为与 write 类似——文件不存在则新建，路径不存在则自动创建。

这两个方法的“自动创建路径”特性大幅减少了前置检查的代码量：

var log = new FileX("/sdcard/app/logs/2026/08/06.log");
log.append("2026-08-06 10:00:00 – 应用启动\\n");
// 即使 logs/2026/08/ 目录不存在，也会自动创建

3. 写入图片与相册更新

文档中特别提到，如果写入的是图片文件且希望该图片在系统相册中显示，需要在写入后调用全局函数 updatePhotoAlbum。这是因为 Android 系统的媒体库不会自动扫描新增的图片文件，需要主动通知系统更新。

var img = new FileX("/sdcard/Pictures/screenshot.png");
img.write(imageData); // imageData 为字节数组
updatePhotoAlbum("/sdcard/Pictures/screenshot.png");

六、总结

冰狐智能辅助平台的文件操作 API 设计遵循了“简洁但完备”的原则。从路径体系的三种形式（全路径、相对路径、资源路径），到文件状态判断、目录遍历、删除移动，再到读写操作中的自动创建路径特性，整体覆盖了移动端自动化开发中绝大部分文件管理需求。

几个值得留意的设计亮点包括：

• 路径自动创建：write 和 append 方法在路径不存在时会自动创建，减少了冗余的前置检查代码。

• 递归删除：remove 方法对非空目录的自动递归删除，简化了清理逻辑，但也需要开发者谨慎使用。

• 字符集支持：读写方法均支持指定字符集，默认 utf-8，兼顾了国际化和灵活性。

• 资源文件访问：asset: 前缀使得打包到 APK 中的资源文件可以被统一方式访问。

在实际开发中，建议根据具体场景合理组合使用这些 API，例如用 exists + isFile 做读取前校验，用 makeDirs + listFiles 管理目录结构，用 write / append 配合日志轮转策略实现持久化存储。掌握这些基础文件操作，是高效使用冰狐平台进行自动化开发的重要一步。