About Files and Directories

The file system is an important part of any operating system. After all, it’s where users keep their stuff. The organization of the file system plays an important role in helping the user find files. The organization also makes it easier for apps and the system itself to find and access the resources they need to support the user.

• 文件系统是任何操作系统的重要组成部分。 毕竟，这是用户保留他们的东西的地方。 文件系统的组织在帮助用户查找文件方面起着重要作用。 该组织还使应用程序和系统本身更容易查找和访问支持用户所需的资源。

This document is intended for developers who are writing software for macOS, iOS, and iCloud. It shows you how to use the system interfaces to access files and directories and how to move files to and from iCloud. This document also provides guidance on how best to work with files, and it shows you where you should be placing any new files you create.

• 本文档适用于为macOS，iOS和iCloud编写软件的开发人员。 它向您展示了如何使用系统界面访问文件和目录以及如何将文件移入和移出iCloud。 本文档还提供了有关如何最好地处理文件的指导，并显示了您应该在何处放置您创建的新文件。

Important: When you adopt App Sandbox in your macOS app, the behavior of many file system features changes. For example, to obtain access to locations outside of your app’s container directory, you must request appropriate entitlements. To obtain persistent access to a file system resource, you must employ the security-scoped bookmark features of the NSURL class or the CFURLRef opaque type. There are changes to the location of app support files (which are relative to your container rather than to the user’s home folder) and to the behavior of Open and Save dialogs (which are presented by the macOS security technology, Powerbox, not AppKit). For details on all these changes, read App Sandbox Design Guide.

• 重要提示：在macOS应用程序中采用App Sandbox时，许多文件系统功能的行为会发生变化。 例如，要获取对应用程序容器目录之外的位置的访问权限，您必须请求相应的权利。 要获得对文件系统资源的持久访问，必须使用NSURL类的安全范围的书签功能或CFURLRef opaque类型。 应用程序支持文件的位置（相对于您的容器而不是用户的主文件夹）以及打开和保存对话框（由macOS安全技术，Powerbox，而不是AppKit呈现）的行为发生了变化。 有关所有这些更改的详细信息，请阅读App Sandbox Design Guide。

At a Glance

To effectively use the file system, you must know what to expect from the file system and which technologies are available for accessing it.

• 要有效地使用文件系统，您必须知道文件系统的期望以及可用于访问它的技术。

The File System Imposes a Specific Organization

• 文件系统强加了一个特定的组织

The file systems in iOS and macOS are structured to help keep files organized, both for the user and for apps. From the perspective of your code, a well-organized file system makes it easier to locate files your app needs. Of course, you also need to know where you should put any files you create.

• iOS和macOS中的文件系统的结构有助于保持文件的组织，包括用户和应用程序。 从代码的角度来看，组织良好的文件系统可以更轻松地找到您的应用所需的文件。 当然，您还需要知道应该在何处放置您创建的文件。

Relevant chapters and appendixes: File System Basics, macOS Library Directory Details, File System Details

Access Files Safely

On a multiuser system like macOS, it is possible that more than one app may attempt to read or write a file at the same time as another app is using it. The NSFileCoordinator and NSFilePresenter classes allow you to maintain file integrity and ensure that if files are made available to other apps (for example, emailing the current TextEdit document) that the most current version is sent.

• 在像macOS这样的多用户系统上，可能有多个应用程序可能在另一个应用程序正在使用它的同时尝试读取或写入文件。 NSFileCoordinator和NSFilePresenter类允许您维护文件完整性，并确保文件可供其他应用程序（例如，通过电子邮件发送当前TextEdit文档）发送最新版本。
  Relevant Chapter: The Role of File Coordinators and Presenters

How You Access a File Depends on the File Type

• 如何访问文件取决于文件类型

Different files require different treatments by your code. For file formats defined by your app, you might read the contents as a binary stream of bytes. For more common file formats, though, iOS and macOS provide higher-level support that make reading and writing those files easier.

• 不同的文件需要您的代码处理不同。 对于应用程序定义的文件格式，您可以将内容读取为二进制字节流。 但是，对于更常见的文件格式，iOS和macOS提供更高级别的支持，使读取和写入这些文件更容易。
  Relevant section: Choose the Right Way to Access Files

System Interfaces Help You Locate and Manage Your Files

• 系统界面可帮助您找到并管理文件

Hard-coded pathnames are fragile and liable to break over time, so the system provides interfaces that search for files in well-known locations. Using these interfaces makes your code more robust and future proof, ensuring that regardless of where files move to, you can still find them.

• 硬编码的路径名很脆弱，可能会随着时间的推移而中断，因此系统提供了在众所周知的位置搜索文件的接口。 使用这些接口可以使您的代码更加强大和面向未来，确保无论文件移动到何处，您仍然可以找到它们。
  Relevant chapter: Accessing Files and Directories

Users Interact with Files Using the Standard System Panels

• 用户使用标准系统面板与文件交互

For files that the user creates and manages, your code can use the standard Open and Save panels to ask for the locations of those files. The standard panels present the user with a navigable version of the file system that matches what the Finder presents. You can use these panels without customization, modify the default behavior, or augment them with your own custom content. Even sandboxed apps can use the panels to access files because they work with the underlying security layer to allow exceptions for files outside of your sandbox that the user explicitly chooses.

• 对于用户创建和管理的文件，您的代码可以使用标准的“打开”和“保存”面板来询问这些文件的位置。 标准面板向用户显示文件系统的可导航版本，该版本与Finder提供的版本相匹配。 您可以使用这些面板而无需自定义，修改默认行为或使用您自己的自定义内容扩充它们。 即使是沙盒应用也可以使用面板来访问文件，因为它们与底层安全层一起使用，以允许用户明确选择的沙箱之外的文件的例外。
  Relevant chapter: Using the Open and Save Panels

Read and Write Files Asynchronously

Because file operations require accessing a disk or network server, you should always access files from a secondary thread of your app. Some of the technologies for reading and writing files run asynchronously without you having to do anything, while others require you to provide your own execution context. All of the technologies do essentially the same thing but offer different levels of simplicity and flexibility.

• 由于文件操作需要访问磁盘或网络服务器，因此应始终从应用程序的辅助线程访问文件。 一些用于读取和写入文件的技术可以异步运行，而无需执行任何操作，而其他技术则要求您提供自己的执行上下文。 所有技术都基本相同，但提供不同级别的简单性和灵活性。
  As you read and write files, you should also use file coordinators to ensure that any actions you take on a file do not cause problems for other apps that care about the file.
• 在读取和写入文件时，您还应该使用文件协调器来确保对文件执行的任何操作都不会对关心该文件的其他应用程序造成问题。
  Relevant chapter: Techniques for Reading and Writing Files Without File Coordinators

Move, Copy, Delete, and Manage Files Like the Finder

The system interfaces support all of the same types of behaviors that the Finder supports and many more. You can move, copy, create, and delete files and directories just like the user can. Using the programmatic interfaces, you can also iterate through the contents of directories and work with invisible files much more efficiently. More importantly, most of the work can be done asynchronously to avoid blocking your app’s main thread.

• 系统接口支持Finder支持的所有相同类型的行为以及更多。 您可以像用户一样移动，复制，创建和删除文件和目录。 使用编程接口，您还可以迭代目录的内容，并更有效地处理不可见的文件。 更重要的是，大多数工作可以异步完成，以避免阻止您的应用程序的主线程。
  Relevant chapter: Managing Files and Directories

Optimize Your File-Related Operations

• 优化与文件相关的操作
  The file system is one of the slowest parts of a computer so writing efficient code is important. Optimizing your file-system code is about minimizing the work you do and making sure that the operations you do perform are done efficiently.
• 文件系统是计算机中最慢的部分之一，因此编写高效的代码非常重要。 优化文件系统代码是为了最大限度地减少您的工作，并确保您执行的操作有效完成。
  Relevant chapter: Performance Tips

See Also

For information about more advanced file-system tasks that you can perform, see File System Advanced Programming Topics.