Titanium SDK 文件系统模块深度解析

Titanium SDK 文件系统模块深度解析

titanium-sdk 🚀 Native iOS and Android Apps with JavaScript 项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk

Titanium SDK 的文件系统模块(Titanium.Filesystem)为开发者提供了跨平台的本地文件访问能力。本文将深入解析该模块的核心功能、使用场景及最佳实践。

模块概述

Titanium.Filesystem 是 Titanium SDK 的核心模块之一，它抽象了不同操作系统间的文件系统差异，为开发者提供了一致的 API 接口。通过该模块，开发者可以：

• 创建和管理文件/目录
• 读写文件内容
• 访问设备上的各类存储位置
• 处理文件权限

核心方法详解

文件操作基础方法

1. getFile() - 获取文件对象

   • 根据路径参数返回 File 对象
   • 不会自动创建文件，需调用 write() 或 createDirectory()
   • 支持相对路径和绝对路径
   • 注意 iOS 上相对路径的特殊处理

2. createTempFile()/createTempDirectory() - 创建临时文件/目录

   • 在系统临时目录中创建
   • 适合短期存储需求

3. openStream() - 打开文件流

   • 支持 MODE_READ/MODE_WRITE/MODE_APPEND 三种模式
   • 返回 FileStream 对象用于流式操作

平台特有方法

1. directoryForSuite() (iOS/macOS)

   • 获取应用组共享目录
   • 需配置正确的 entitlements

2. getAsset() (iOS/macOS)

   • 专用于访问 Asset Catalog 中的资源
   • 解决 iOS 应用瘦身后的资源访问问题

3. 存储权限相关方法 (Android)

   • hasStoragePermissions() - 检查权限状态
   • requestStoragePermissions() - 请求权限
   • 支持 Promise 和回调两种方式

重要目录属性

Titanium 提供了多个预定义目录路径，开发者应根据文件用途选择合适的存储位置：

| 属性名称 | 适用平台 | 用途说明 | |---------|---------|---------| | applicationDataDirectory | 全平台 | 用户文档存储，iOS 会自动备份 | | applicationSupportDirectory | iOS/macOS | 非用户文档的应用数据 | | applicationCacheDirectory | 全平台 | 临时缓存，系统可能清理 | | tempDirectory | 全平台 | 临时文件，应用关闭后不保证保留 | | externalStorageDirectory | Android | 外部存储(如SD卡)，适合大文件 | | resourcesDirectory | 全平台 | 只读，存放应用资源文件 | | resRawDirectory | Android | 特殊资源目录，如通知音效 |

iOS 文件保护级别

iOS 提供了多种文件保护级别，通过以下常量设置：

• IOS_FILE_PROTECTION_NONE - 无保护
• IOS_FILE_PROTECTION_COMPLETE - 设备锁定时不可访问
• IOS_FILE_PROTECTION_COMPLETE_UNLESS_OPEN - 已打开文件可继续访问
• IOS_FILE_PROTECTION_COMPLETE_UNTIL_FIRST_USER_AUTHENTICATION - 首次解锁后即可访问

最佳实践

1. 路径处理

   • 使用 separator 属性处理跨平台路径分隔符
   • 使用 lineEnding 处理跨平台换行符

2. 存储选择

   • 小量用户数据 → applicationDataDirectory
   • 大量缓存数据 → applicationCacheDirectory 或 externalStorageDirectory
   • 临时计算数据 → tempDirectory

3. 权限管理

   • Android 6.0+ 需要动态请求存储权限
   • 使用 hasStoragePermissions() 检查状态
   • 优雅处理用户拒绝权限的情况

4. iOS 特殊处理

   • 应用瘦身后使用 getAsset() 访问图片资源
   • 敏感数据使用适当的文件保护级别
   • 应用组间共享使用 directoryForSuite()

示例代码

// 写入用户数据
var userFile = Ti.Filesystem.getFile(
    Ti.Filesystem.applicationDataDirectory,
    'userdata.json'
);
userFile.write(JSON.stringify(userData));

// 读取缓存数据
var cacheFile = Ti.Filesystem.getFile(
    Ti.Filesystem.applicationCacheDirectory,
    'cachedata.dat'
);
if(cacheFile.exists()) {
    var cacheData = cacheFile.read();
}

// Android 权限请求
if(!Ti.Filesystem.hasStoragePermissions()) {
    Ti.Filesystem.requestStoragePermissions(function(e) {
        if(e.success) {
            // 权限已授予
        } else {
            // 处理拒绝情况
        }
    });
}

通过合理利用 Titanium.Filesystem 模块，开发者可以构建出高效、安全的本地存储解决方案，同时保持跨平台的一致性。

titanium-sdk 🚀 Native iOS and Android Apps with JavaScript 项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk