FileManager.default.url API 文档

概述

FileManager.default.url(for:in:appropriateFor:create:) 是 Swift 中 FileManager 类的一个方法，用于返回指定域中特定目录的 URL。它是文件系统操作的核心 API，推荐使用 URL 而不是字符串路径，因为 URL 提供更好的错误处理和跨平台兼容性。该方法适用于定位如文档目录、缓存目录、临时目录等标准目录。

方法签名：

func url(
    for directory: FileManager.SearchPathDirectory,
    in domain: FileManager.SearchPathDomainMask,
    appropriateFor url: URL?,
    create: Bool
) throws -> URL

参数说明

以下是 url(for:in:appropriateFor:create:) 方法的所有参数及其详细说明：

directory: FileManager.SearchPathDirectory
- 描述: 指定要查找的目录类型。这是一个枚举类型，定义了常见的文件系统目录。
- 常见值:
  - .documentDirectory: 用户文档目录（~/Documents 或应用沙盒内的文档目录）。
  - .cachesDirectory: 缓存目录，适合存储可被重新生成的数据。
  - .applicationSupportDirectory: 应用支持目录，适合存储应用数据。
  - .temporaryDirectory: 临时目录，适合存储短期数据。
  - .itemReplacementDirectory: 用于临时替换文件的目录（仅在 userDomainMask 中有效）。
  - .trashDirectory: 垃圾箱目录。
  - 其他值包括 .libraryDirectory、.desktopDirectory、.downloadsDirectory 等，具体支持取决于平台。
- 注意: 不同平台支持的目录类型可能不同。例如，.desktopDirectory 在 iOS 上可能不可用。
domain: FileManager.SearchPathDomainMask
- 描述: 指定搜索目录的域，决定了查找的范围。
- 常见值:
  - .userDomainMask: 用户主目录（~），如 ~/Documents。
  - .localDomainMask: 本地系统范围，如 /Library。
  - .networkDomainMask: 网络共享目录。
  - .systemDomainMask: 系统目录，如 /System。
  - .allDomainsMask: 包含所有域（用户、本地、网络、系统）。
- 注意: 在 iOS 沙盒环境中，.userDomainMask 是最常用的域，其他域可能受限。
appropriateFor: URL?
- 描述: 一个可选的 URL 参数，用于指定目标目录所在的卷（volume）。主要用于 .itemReplacementDirectory 和 .trashDirectory，以确保返回的 URL 位于同一卷上，从而优化文件操作性能（如避免跨卷拷贝）。
- 用法:
  - 如果 directory 是 .itemReplacementDirectory 或 .trashDirectory，且 domain 是 .userDomainMask，则 appropriateFor 的卷信息会被使用。
  - 对于其他目录类型，appropriateFor 通常被忽略，可以传入 nil。
- 示例:
```
let desktopURL = URL(fileURLWithPath: "/Users/Username/Desktop/")
let tempURL = try FileManager.default.url(
    for: .itemReplacementDirectory,
    in: .userDomainMask,
    appropriateFor: desktopURL,
    create: true
)
```
  在此例中，
```
tempURL
```
  将位于与
```
desktopURL
```
  相同的卷上。
create: Bool
- 描述: 指定是否在目标目录不存在时创建它。
- 值:
  - true: 如果目录不存在，尝试创建它。
  - false: 如果目录不存在，将抛出错误。
- 注意: 创建目录可能失败（例如权限不足），需要处理抛出的错误。

返回值

类型: URL
描述: 返回指定目录的 URL。如果目录不存在且 create 为 false，或因其他原因（如权限问题）无法访问，将抛出错误。

抛出错误

该方法使用
```
throws
```
关键字，可能抛出
```
Foundation
```
框架中的错误，例如：
- NSFileNoSuchFileError: 目录不存在且 create 为 false。
- NSFileWriteNoPermissionError: 没有权限创建或访问目录。
- 其他文件系统相关错误。

使用示例

以下是一个使用 FileManager.default.url 创建子目录的示例：

import Foundation

let fileManager = FileManager.default

do {
    // 获取用户文档目录
    let documentURL = try fileManager.url(
        for: .documentDirectory,
        in: .userDomainMask,
        appropriateFor: nil,
        create: false
    )
    
    // 创建子目录
    let subFolderURL = documentURL.appendingPathComponent("MyFolder/SubFolder")
    if !fileManager.fileExists(atPath: subFolderURL.path) {
        try fileManager.createDirectory(
            at: subFolderURL,
            withIntermediateDirectories: true,
            attributes: nil
        )
        print("目录创建成功: \(subFolderURL.path)")
    }
} catch {
    print("错误: \(error.localizedDescription)")
}

输出:

目录创建成功: /Users/Username/Documents/MyFolder/SubFolder

注意事项

URL vs 字符串路径:
- 推荐使用 FileManager.default.url 而不是 NSSearchPathForDirectoriesInDomains，因为 URL API 提供更好的错误处理和跨平台支持。
- 避免使用 absoluteString 获取路径，应使用 path 属性以确保正确处理文件系统路径。
沙盒环境:
- 在 iOS 应用中，FileManager 操作受限于应用沙盒，.userDomainMask 是最常用的域。
性能优化:
- 对于 .itemReplacementDirectory，使用 appropriateFor 参数可以确保临时目录与目标文件在同一卷上，减少跨卷操作的开销。
错误处理:
- 总是使用 do-catch 块捕获潜在错误，以确保程序健壮性。

参考资料

Apple 开发者文档: url(for:in:appropriateFor:create:)
Stack Overflow: When should we use FileManager.default.urls as opposed to NSSearchPathForDirectoriesInDomains?
Swift by Sundell: Working with files and folders in Swift