在搭载 Android 4.4（API 级别 19）及更高版本的设备上，您的应用可以使用存储访问框架与包括外部存储卷和云端存储空间在内的文档提供器互动。此框架支持用户与系统选择器互动，从而选择文档提供器以及供您的应用创建、打开或修改的特定文档和其他文件。

由于用户参与选择您的应用可以访问的文件或目录，因此该机制无需任何系统权限，同时用户控制和隐私保护也得到了增强。此外，这些文件存储在应用专属目录和媒体库之外，在应用卸载后仍会保留在设备上。

使用存储访问框架涉及以下步骤：

1. 应用调用包含存储相关操作的 intent。此操作对应于框架支持的特定用例。
2. 用户看到一个系统选择器，供其浏览文档提供器并选择将执行存储相关操作的位置或文档。
3. 应用获得对代表用户所选位置或文档的 URI 的读写访问权限。利用该 URI，应用可以在选择的位置执行操作。

如需在搭载 Android 9（API 级别 28）或更低版本的设备上支持媒体文件访问，请声明 权限并将 设为 。

本指南介绍了存储访问框架支持的访问文件和其他文档的不同用例。另外，还介绍了如何在用户选择的位置执行操作。

存储访问框架支持以下访问文件和其他文档的用例。

创建新文件

intent 操作支持用户将文件保存在特定位置。

打开文档或文件

intent 操作支持用户选择要打开的特定文档或文件。

授予对目录内容的访问权限

intent 操作在 Android 5.0（API 级别 21）及更高版本中提供，支持用户选择特定目录，授予应用对该目录中所有文件和子目录的访问权限。

以下几个部分分别提供了关于每个用例的配置指导。

使用 intent 操作加载系统文件选择器，支持用户选择要写入文件内容的位置。此流程类似于其他操作系统使用的“另存为”对话框中使用的流程。

在配置 intent 时，应指定文件的名称和 MIME 类型，并且还可以根据需要使用 intent extra 指定文件选择器在首次加载时应显示的文件或目录的 URI。

以下代码段展示了如何创建和调用用于创建文件的 intent：

您的应用可以使用文档作为存储单元，供用户在其中输入可能要与同伴分享或要导入到其他文档的数据。例如，用户打开办公文档或打开另存为 EPUB 文件的图书。

在此类情况下，请通过调用 intent 来支持用户选择要打开的文件，此 intent 会打开系统的文件选择器应用。若要仅显示应用支持的文件类型，请指定 MIME 类型。此外，您还可以根据需要使用 intent extra 指定文件选择器在首次加载时应显示的文件的 URI。

以下代码段展示了如何创建和调用用于打开 PDF 文档的 intent：

在 Android 11（API 级别 30）及更高版本中，您不能使用 intent 操作来请求用户从以下目录中选择单独的文件：

• 目录及其所有子目录。
• 目录及其所有子目录。

文件管理和媒体创建应用通常在目录层次结构中管理文件组。如需在您的应用中提供此功能，请使用 intent 操作，它支持用户授予应用对整个目录树的访问权限，但在 Android 11（API 级别 30）及以上版本中会有一些例外情况。然后，您的应用便可以访问所选目录及其任何子目录中的任何文件。

使用 时，您的应用只能访问用户所选目录中的文件。您无权访问位于用户所选目录之外的其他应用的文件。借助这种由用户控制的访问权限，用户可以确切选择自己想要与您的应用共享的具体内容。

您可以根据需要使用 intent extra 指定文件选择器在首次加载时应显示的目录的 URI。

以下代码段展示了如何创建和调用用于打开目录的 intent：

在 Android 11（API 级别 30）及更高版本中，您不能使用 intent 操作来请求访问以下目录：

• 内部存储卷的根目录。
• 设备制造商认为可靠的各个 SD 卡卷的根目录，无论该卡是模拟卡还是可移除的卡。可靠的卷是指应用在大多数情况下可以成功访问的卷。
• 目录。

此外，在 Android 11（API 级别 30）及更高版本中，您不能使用 intent 操作来请求用户从以下目录中选择单独的文件：

• 目录及其所有子目录。
• 目录及其所有子目录。

在用户使用系统的文件选择器选择文件或目录后，您可以在 中使用以下代码检索所选项目的 URI：

讯享网

获取对所选项目 URI 的引用后，您的应用可以对该项目执行多项操作。例如，您可以访问该项目的元数据，在原位置修改该项目，以及删除该项目。

以下几个部分介绍了如何对用户选择的文件完成各种操作。

不同的内容提供器支持对文档执行不同的操作，例如复制文档或查看文档的缩略图。如需确定指定提供器支持哪些操作，请查看 的值。应用的界面只会显示提供器支持的选项。

当您的应用打开文件进行读取或写入时，系统会向应用授予对该文件的 URI 的访问权限，该授权在用户重启设备之前一直有效。但是，假设您的应用是图片编辑应用，而且您希望用户能够直接从应用中访问他们最近修改的 5 张图片，那么在用户重启设备后，您就必须让用户返回到系统选择器来查找这些文件。

如需在设备重启后保留对文件的访问权限并提供更出色的用户体验，您的应用可以“获取”系统提供的永久性 URI 访问权限，如以下代码段所示：

获得文档的 URI 后，您便可以访问该文档的元数据。以下代码段用于获取 URI 所指定文档的元数据，并将其记入日志：

获取对文档 URI 的引用后，您可以打开文档进行进一步处理。本部分介绍了打开位图和输入流的示例。

位图

以下代码段显示了如何在已获得 文件的 URI 的情况下打开该文件：

打开位图后，您可以在 中显示该位图。

输入流

以下代码段显示了如何在已获得 InputStream 对象的 URI 的情况下打开该对象。在此代码段中，系统会将文件行读取到字符串中：

您可以使用存储访问框架在原位置修改文本文档。

以下代码段会覆盖给定 URI 所代表的文档的内容：

如果您获得了文档的 URI，并且该文档的 包含 ，您便可以删除该文档。例如：

方法可提供与给定文档提供程序 URI 等效的媒体 URI。这两个 URI 指的是同一个基础项。使用媒体库 URI，您可以更轻松地访问共享存储空间中的媒体文件。

方法支持 URI。在 Android 12（API 级别 31）及更高版本中，此方法还支持 URI。

在 Android 7.0（API 级别 25）及更高版本中，您的应用可以使用存储访问框架提供的虚拟文件。即使虚拟文件没有二进制文件表示形式，您的应用也可以通过以下方法打开文件中的内容：将虚拟文件强制转换为其他文件类型，或使用 intent 操作查看这些文件。

为了打开虚拟文件，您的客户端应用需要包含用于处理此类文件的特殊逻辑。如果您想要获取文件的字节表示形式（例如，为了预览文件），您需要从文档提供器请求其他 MIME 类型。

在用户做出选择后，请使用结果数据中的 URI 来确定文件是否为虚拟文件，如以下代码段所示：

在验证文档为虚拟文件后，您可以将其强制转换为另一种 MIME 类型，例如 。以下代码段展示了如何查看某个虚拟文件是否可以表示为图片，如果可以，则从该虚拟文件获取输入流：

如需详细了解如何存储和访问文档及其他文件，请参阅以下资源。

• ，可在 GitHub 上获取。
• ，可在 GitHub 上获取。

• 为采用分区存储做好准备（2019 年 Android 开发者峰会）