在搭载 Android 4.4(API 级别 19)及更高版本的设备上,您的应用可以使用 Storage Access Framework 与文档提供程序进行交互,包括外部存储卷和基于云的存储。此框架允许用户与系统选择器交互,以选择文档提供程序并选择特定文档和其他文件供您的应用创建、打开或修改。
由于用户参与选择您的应用可以访问的文件或目录,此机制不需要任何系统权限,并且增强了用户控制和隐私。此外,这些存储在应用专属目录之外和媒体库之外的文件,在您的应用卸载后仍保留在设备上。
使用此框架涉及以下步骤
- 应用调用包含与存储相关的操作的 intent。此操作对应于框架提供的特定用例。
- 用户看到系统选择器,允许他们浏览文档提供程序并选择进行与存储相关的操作的位置或文档。
- 应用获得对表示用户选择的位置或文档的 URI 的读写访问权限。使用此 URI,应用可以在所选位置执行操作。
为了在运行 Android 9(API 级别 28)或更低版本的设备上支持媒体文件访问,请声明 READ_EXTERNAL_STORAGE
权限并将 maxSdkVersion
设置为 28
。
本指南介绍了框架支持的不同文件和其他文档使用案例。它还说明了如何在用户选择的位置上执行操作。
访问文档和其他文件的用例
Storage Access Framework 支持以下访问文件和其他文档的用例。
- 创建新文件
- 的
ACTION_CREATE_DOCUMENT
Intent 操作允许用户将文件保存到特定位置。 - 打开文档或文件
- 的
ACTION_OPEN_DOCUMENT
Intent 操作允许用户选择要打开的特定文档或文件。 - 授予访问目录内容的权限
ACTION_OPEN_DOCUMENT_TREE
Intent 操作(适用于 Android 5.0(API 级别 21)及更高版本)允许用户选择特定目录,授予您的应用访问该目录中所有文件和子目录的权限。
以下各部分提供了关于如何配置各个用例的指导。
创建新文件
使用 ACTION_CREATE_DOCUMENT
Intent 操作加载系统文件选择器,并允许用户选择要写入文件内容的位置。此过程类似于其他操作系统使用的“另存为”对话框。
注意:ACTION_CREATE_DOCUMENT
不能覆盖现有文件。如果您的应用尝试保存同名文件,系统将在文件名末尾追加一个带括号的数字。
例如,如果您的应用尝试将名为 confirmation.pdf
的文件保存在已存在同名文件的目录中,系统将以 confirmation(1).pdf
的名称保存新文件。
配置 Intent 时,请指定文件的名称和 MIME 类型,并可选择使用 EXTRA_INITIAL_URI
Intent extra 指定文件选择器首次加载时应显示的 URI。
以下代码段展示了如何创建和调用用于创建文件的 Intent
Kotlin
// Request code for creating a PDF document. const val CREATE_FILE = 1 private fun createFile(pickerInitialUri: Uri) { val intent = Intent(Intent.ACTION_CREATE_DOCUMENT).apply { addCategory(Intent.CATEGORY_OPENABLE) type = "application/pdf" putExtra(Intent.EXTRA_TITLE, "invoice.pdf") // Optionally, specify a URI for the directory that should be opened in // the system file picker before your app creates the document. putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri) } startActivityForResult(intent, CREATE_FILE) }
Java
// Request code for creating a PDF document. private static final int CREATE_FILE = 1; private void createFile(Uri pickerInitialUri) { Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT); intent.addCategory(Intent.CATEGORY_OPENABLE); intent.setType("application/pdf"); intent.putExtra(Intent.EXTRA_TITLE, "invoice.pdf"); // Optionally, specify a URI for the directory that should be opened in // the system file picker when your app creates the document. intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri); startActivityForResult(intent, CREATE_FILE); }
打开文件
您的应用可能使用文档作为存储单元,用户可以在其中输入他们想要与同行共享或导入到其他文档的数据。一些示例包括用户打开生产力文档或打开保存为 EPUB 文件的图书。
在这些情况下,通过调用 ACTION_OPEN_DOCUMENT
Intent 来允许用户选择要打开的文件,这将打开系统的文件选择器应用。要仅显示您的应用支持的文件类型,请指定 MIME 类型。此外,您还可以选择使用 EXTRA_INITIAL_URI
Intent extra 指定文件选择器首次加载时应显示的文件的 URI。
以下代码段展示了如何创建和调用用于打开 PDF 文档的 Intent
Kotlin
// Request code for selecting a PDF document. const val PICK_PDF_FILE = 2 fun openFile(pickerInitialUri: Uri) { val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply { addCategory(Intent.CATEGORY_OPENABLE) type = "application/pdf" // Optionally, specify a URI for the file that should appear in the // system file picker when it loads. putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri) } startActivityForResult(intent, PICK_PDF_FILE) }
Java
// Request code for selecting a PDF document. private static final int PICK_PDF_FILE = 2; private void openFile(Uri pickerInitialUri) { Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT); intent.addCategory(Intent.CATEGORY_OPENABLE); intent.setType("application/pdf"); // Optionally, specify a URI for the file that should appear in the // system file picker when it loads. intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri); startActivityForResult(intent, PICK_PDF_FILE); }
访问限制
在 Android 11(API 级别 30)及更高版本上,您不能使用 ACTION_OPEN_DOCUMENT
Intent 操作请求用户从以下目录中选择单个文件
Android/data/
目录及其所有子目录。Android/obb/
目录及其所有子目录。
授予访问目录内容的权限
文件管理和媒体创建应用通常在目录层次结构中管理文件组。为了在您的应用中提供此功能,请使用 ACTION_OPEN_DOCUMENT_TREE
Intent 操作,该操作允许用户授予对整个目录树的访问权限,从 Android 11(API 级别 30)开始有一些例外情况。然后,您的应用可以访问所选目录及其任何子目录中的任何文件。
使用 ACTION_OPEN_DOCUMENT_TREE
时,您的应用只能访问用户选择的目录中的文件。您无权访问位于此用户选择的目录之外的其他应用的文件。这种用户控制的访问方式允许用户精确选择他们愿意与您的应用共享的内容。
您还可以选择使用 EXTRA_INITIAL_URI
Intent extra 指定文件选择器首次加载时应显示的目录的 URI。
以下代码段展示了如何创建和调用用于打开目录的 Intent
Kotlin
fun openDirectory(pickerInitialUri: Uri) { // Choose a directory using the system's file picker. val intent = Intent(Intent.ACTION_OPEN_DOCUMENT_TREE).apply { // Optionally, specify a URI for the directory that should be opened in // the system file picker when it loads. putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri) } startActivityForResult(intent, your-request-code) }
Java
public void openDirectory(Uri uriToLoad) { // Choose a directory using the system's file picker. Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE); // Optionally, specify a URI for the directory that should be opened in // the system file picker when it loads. intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, uriToLoad); startActivityForResult(intent, your-request-code); }
访问限制
在 Android 11(API 级别 30)及更高版本上,您不能使用 ACTION_OPEN_DOCUMENT_TREE
Intent 操作请求访问以下目录
- 内部存储卷的根目录。
- 设备制造商视为可靠的每个 SD 卡卷的根目录,无论该卡是模拟的还是可移动的。可靠卷是指应用在大多数情况下可以成功访问的卷。
Download
目录。
此外,在 Android 11(API 级别 30)及更高版本上,您不能使用 ACTION_OPEN_DOCUMENT_TREE
Intent 操作请求用户从以下目录中选择单个文件
Android/data/
目录及其所有子目录。Android/obb/
目录及其所有子目录。
在所选位置执行操作
用户使用系统的文件选择器选择文件或目录后,您可以在 onActivityResult()
中使用以下代码检索所选项目的 URI
Kotlin
override fun onActivityResult( requestCode: Int, resultCode: Int, resultData: Intent?) { if (requestCode == your-request-code && resultCode == Activity.RESULT_OK) { // The result data contains a URI for the document or directory that // the user selected. resultData?.data?.also { uri -> // Perform operations on the document using its URI. } } }
Java
@Override public void onActivityResult(int requestCode, int resultCode, Intent resultData) { if (requestCode == your-request-code && resultCode == Activity.RESULT_OK) { // The result data contains a URI for the document or directory that // the user selected. Uri uri = null; if (resultData != null) { uri = resultData.getData(); // Perform operations on the document using its URI. } } }
通过获取所选项目的 URI 引用,您的应用可以对该项目执行多项操作。例如,您可以访问项目的元数据、就地编辑项目以及删除项目。
以下各节展示了如何对用户选择的文件执行操作。
确定提供程序支持的操作
不同的内容提供程序允许对文档执行不同的操作,例如复制文档或查看文档缩略图。要确定给定提供程序支持哪些操作,请检查 Document.COLUMN_FLAGS
的值。然后,您的应用的 UI 只能显示提供程序支持的选项。
持久化权限
当您的应用打开文件进行读写时,系统会授予您的应用对该文件的 URI 权限,该权限持续到用户设备重启。但是,假设您的应用是一个图片编辑应用,并且您希望用户可以直接从您的应用访问他们最近编辑的 5 张图片。如果用户的设备已重启,您将不得不将用户发送回系统选择器来查找文件。
为了在设备重启后仍保留对文件的访问权限并提供更好的用户体验,您的应用可以“获取”系统提供的持久化 URI 权限,如下面的代码片段所示
Kotlin
val contentResolver = applicationContext.contentResolver val takeFlags: Int = Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION // Check for the freshest data. contentResolver.takePersistableUriPermission(uri, takeFlags)
Java
final int takeFlags = intent.getFlags() & (Intent.FLAG_GRANT_READ_URI_PERMISSION | Intent.FLAG_GRANT_WRITE_URI_PERMISSION); // Check for the freshest data. getContentResolver().takePersistableUriPermission(uri, takeFlags);
检查文档元数据
当您拥有文档的 URI 时,您就可以访问其元数据。此代码段获取由 URI 指定的文档的元数据并进行日志记录
Kotlin
val contentResolver = applicationContext.contentResolver fun dumpImageMetaData(uri: Uri) { // The query, because it only applies to a single document, returns only // one row. There's no need to filter, sort, or select fields, // because we want all fields for one document. val cursor: Cursor? = contentResolver.query( uri, null, null, null, null, null) cursor?.use { // moveToFirst() returns false if the cursor has 0 rows. Very handy for // "if there's anything to look at, look at it" conditionals. if (it.moveToFirst()) { // Note it's called "Display Name". This is // provider-specific, and might not necessarily be the file name. val displayName: String = it.getString(it.getColumnIndex(OpenableColumns.DISPLAY_NAME)) Log.i(TAG, "Display Name: $displayName") val sizeIndex: Int = it.getColumnIndex(OpenableColumns.SIZE) // If the size is unknown, the value stored is null. But because an // int can't be null, the behavior is implementation-specific, // and unpredictable. So as // a rule, check if it's null before assigning to an int. This will // happen often: The storage API allows for remote files, whose // size might not be locally known. val size: String = if (!it.isNull(sizeIndex)) { // Technically the column stores an int, but cursor.getString() // will do the conversion automatically. it.getString(sizeIndex) } else { "Unknown" } Log.i(TAG, "Size: $size") } } }
Java
public void dumpImageMetaData(Uri uri) { // The query, because it only applies to a single document, returns only // one row. There's no need to filter, sort, or select fields, // because we want all fields for one document. Cursor cursor = getActivity().getContentResolver() .query(uri, null, null, null, null, null); try { // moveToFirst() returns false if the cursor has 0 rows. Very handy for // "if there's anything to look at, look at it" conditionals. if (cursor != null && cursor.moveToFirst()) { // Note it's called "Display Name". This is // provider-specific, and might not necessarily be the file name. String displayName = cursor.getString( cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)); Log.i(TAG, "Display Name: " + displayName); int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE); // If the size is unknown, the value stored is null. But because an // int can't be null, the behavior is implementation-specific, // and unpredictable. So as // a rule, check if it's null before assigning to an int. This will // happen often: The storage API allows for remote files, whose // size might not be locally known. String size = null; if (!cursor.isNull(sizeIndex)) { // Technically the column stores an int, but cursor.getString() // will do the conversion automatically. size = cursor.getString(sizeIndex); } else { size = "Unknown"; } Log.i(TAG, "Size: " + size); } } finally { cursor.close(); } }
打开文档
通过拥有文档 URI 的引用,您可以打开文档进行进一步处理。本节展示了打开位图和输入流的示例。
位图
以下代码段展示了如何给定 URI 打开 Bitmap
文件
Kotlin
val contentResolver = applicationContext.contentResolver @Throws(IOException::class) private fun getBitmapFromUri(uri: Uri): Bitmap { val parcelFileDescriptor: ParcelFileDescriptor = contentResolver.openFileDescriptor(uri, "r") val fileDescriptor: FileDescriptor = parcelFileDescriptor.fileDescriptor val image: Bitmap = BitmapFactory.decodeFileDescriptor(fileDescriptor) parcelFileDescriptor.close() return image }
Java
private Bitmap getBitmapFromUri(Uri uri) throws IOException { ParcelFileDescriptor parcelFileDescriptor = getContentResolver().openFileDescriptor(uri, "r"); FileDescriptor fileDescriptor = parcelFileDescriptor.getFileDescriptor(); Bitmap image = BitmapFactory.decodeFileDescriptor(fileDescriptor); parcelFileDescriptor.close(); return image; }
打开位图后,您可以将其显示在 ImageView
中。
输入流
以下代码段展示了如何给定 URI 打开 InputStream 对象。在此代码段中,文件的行被读入字符串
Kotlin
val contentResolver = applicationContext.contentResolver @Throws(IOException::class) private fun readTextFromUri(uri: Uri): String { val stringBuilder = StringBuilder() contentResolver.openInputStream(uri)?.use { inputStream -> BufferedReader(InputStreamReader(inputStream)).use { reader -> var line: String? = reader.readLine() while (line != null) { stringBuilder.append(line) line = reader.readLine() } } } return stringBuilder.toString() }
Java
private String readTextFromUri(Uri uri) throws IOException { StringBuilder stringBuilder = new StringBuilder(); try (InputStream inputStream = getContentResolver().openInputStream(uri); BufferedReader reader = new BufferedReader( new InputStreamReader(Objects.requireNonNull(inputStream)))) { String line; while ((line = reader.readLine()) != null) { stringBuilder.append(line); } } return stringBuilder.toString(); }
编辑文档
您可以使用 Storage Access Framework 就地编辑文本文档。
以下代码段覆盖给定 URI 表示的文档内容
Kotlin
val contentResolver = applicationContext.contentResolver private fun alterDocument(uri: Uri) { try { contentResolver.openFileDescriptor(uri, "w")?.use { FileOutputStream(it.fileDescriptor).use { it.write( ("Overwritten at ${System.currentTimeMillis()}\n") .toByteArray() ) } } } catch (e: FileNotFoundException) { e.printStackTrace() } catch (e: IOException) { e.printStackTrace() } }
Java
private void alterDocument(Uri uri) { try { ParcelFileDescriptor pfd = getActivity().getContentResolver(). openFileDescriptor(uri, "w"); FileOutputStream fileOutputStream = new FileOutputStream(pfd.getFileDescriptor()); fileOutputStream.write(("Overwritten at " + System.currentTimeMillis() + "\n").getBytes()); // Let the document provider know you're done by closing the stream. fileOutputStream.close(); pfd.close(); } catch (FileNotFoundException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } }
删除文档
如果您拥有文档的 URI 并且该文档的 Document.COLUMN_FLAGS
包含 SUPPORTS_DELETE
,您可以删除该文档。例如
Kotlin
DocumentsContract.deleteDocument(applicationContext.contentResolver, uri)
Java
DocumentsContract.deleteDocument(applicationContext.contentResolver, uri);
检索等效的媒体 URI
getMediaUri()
方法提供了一个媒体库 URI,该 URI 等效于给定的文档提供程序 URI。这两个 URI 指向相同的底层项目。使用媒体库 URI,您可以更轻松地从共享存储空间访问媒体文件。
getMediaUri()
方法支持 ExternalStorageProvider
URI。在 Android 12(API 级别 31)及更高版本上,此方法还支持 MediaDocumentsProvider
URI。
打开虚拟文件
在 Android 7.0(API 级别 25)及更高版本上,您的应用可以使用 Storage Access Framework 提供的虚拟文件。尽管虚拟文件没有二进制表示形式,但您的应用可以通过将其强制转换为不同的文件类型或使用 ACTION_VIEW
Intent 操作来查看这些文件,从而打开其内容。
要打开虚拟文件,您的客户端应用需要包含特殊逻辑来处理它们。例如,如果您想获取文件的字节表示形式以预览文件,您需要从文档提供程序请求备用 MIME 类型。
用户进行选择后,使用结果数据中的 URI 来确定文件是否为虚拟文件,如下面的代码片段所示
Kotlin
private fun isVirtualFile(uri: Uri): Boolean { if (!DocumentsContract.isDocumentUri(this, uri)) { return false } val cursor: Cursor? = contentResolver.query( uri, arrayOf(DocumentsContract.Document.COLUMN_FLAGS), null, null, null ) val flags: Int = cursor?.use { if (cursor.moveToFirst()) { cursor.getInt(0) } else { 0 } } ?: 0 return flags and DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT != 0 }
Java
private boolean isVirtualFile(Uri uri) { if (!DocumentsContract.isDocumentUri(this, uri)) { return false; } Cursor cursor = getContentResolver().query( uri, new String[] { DocumentsContract.Document.COLUMN_FLAGS }, null, null, null); int flags = 0; if (cursor.moveToFirst()) { flags = cursor.getInt(0); } cursor.close(); return (flags & DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT) != 0; }
验证文档是虚拟文件后,您可以将其强制转换为备用 MIME 类型,例如 "image/png"
。以下代码片段展示了如何检查虚拟文件是否可以表示为图像,如果是,则从虚拟文件获取输入流
Kotlin
@Throws(IOException::class) private fun getInputStreamForVirtualFile( uri: Uri, mimeTypeFilter: String): InputStream { val openableMimeTypes: Array<String>? = contentResolver.getStreamTypes(uri, mimeTypeFilter) return if (openableMimeTypes?.isNotEmpty() == true) { contentResolver .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null) .createInputStream() } else { throw FileNotFoundException() } }
Java
private InputStream getInputStreamForVirtualFile(Uri uri, String mimeTypeFilter) throws IOException { ContentResolver resolver = getContentResolver(); String[] openableMimeTypes = resolver.getStreamTypes(uri, mimeTypeFilter); if (openableMimeTypes == null || openableMimeTypes.length < 1) { throw new FileNotFoundException(); } return resolver .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null) .createInputStream(); }
其他资源
如需详细了解如何存储和访问文档及其他文件,请参阅以下资源。
示例
- ActionOpenDocument,可在 GitHub 上获取。
- ActionOpenDocumentTree,可在 GitHub 上获取。