因为最近项目需要，涉及到 SD卡 的读写操作，然而申请
<!-- 读写权限 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
权限只能对 SD卡 进行读操作，而没有写权限，也就是说，Android 在某个版本中对 SD卡 的读写权限进行了限制。后在 StackoverFlow 上找到一篇相关问答，解了心中疑惑。在此，对该问答进行翻译并附上相关 Demo，已做备忘。
原文地址：How to use the new SD card access API presented for Android 5.0 (Lollipop)?
问
背景
在 Android 4.4(KitKat) 中，Google 对 SD卡 的访问已经做了严格的限制。
在 Android 5.0(Lollipop) 中，开发者可以使用 新API 要求用户对某个指定的文件夹进行访问授权，详见：Android 4.4 Samsung Galaxy s4 external sd card is now read only, Remove or option to edit non app files.(译者注：开头挺搞笑的，都是开发者吐槽 Google 对 SD卡 做了限制)
问题
上述文章中有两个链接：
-
此链接中代码看起来更像是内部示例(可能会在以后的 API Demo 中出现)，但是真的很难理解这部分代码的意图。
-
http://developer.android.com/reference/android/support/v4/provider/DocumentFile.html
这是 新API 的官方文档，但是并没有多少如何使用的细节。(译者注：这份文档其实还是有很多内容的，后面会具体细讲。至于为什么会有这种差别，可能作者提问时，该文档尚未完善吧~)
If you really do need full access to an entire subtree of documents, start by launching ACTION_OPEN_DOCUMENT_TREE to let the user pick a directory. Then pass the resulting getData() into fromTreeUri(Context, Uri) to start working with the user selected tree.
As you navigate the tree of DocumentFile instances, you can always use getUri() to obtain the Uri representing the underlying document for that object, for use with openInputStream(Uri), etc.
To simplify your code on devices running KITKAT or earlier, you can use fromFile(File) which emulates the behavior of a DocumentsProvider.
对于新 API 我有以下问题：
- 新 API 的正确使用方式？
- 根据文档，系统会记录 app 被授予访问权限的文件和文件夹。那么，我该如何检测我对某个文件或者文件夹是否有访问权限？是否有方法获取可访问的文件或文件夹列表呢？
- 在 Android 4.4 上如何处理这个问题？Support Library 是否包含相应的解决方案
- 系统中是否有对应的界面可以查看哪些 App 可以访问哪些文件。
- 在多用户的设备上授权该如何处理？
- 是否有其它关于新 API 的文档？
- 对 SD卡 的授权是否可以被取消？如果是，那对应的意图是什么？
- 对于文件夹授权是否是递归授权？指代文件夹内还嵌套有文件夹。
- SD 授权是否支持多选？或该应用程序需要专门告诉意图要允许的文件/文件夹吗？
- 模拟器可以测试新 API 嘛？我的意思是，模拟器具有 SD 卡的分区，但它的作用是主要的外部存储，简单使用
android.permission.WRITE_EXTERNAL_STORAGE是否足够？ - 当用户替换 SD卡 是会发生什么？
来自 Jeff Sharkey 的回答
这些问题问的都非常好，让我们来深入挖掘下
如何使用新的 API
在 Kitkat 中有一份非常好的关于与 Storage Access Framework 交互的文档：Document provider.
新 API 的使用与之很相似。通过发送以下 Intent ，让用户在文档树(Directory Tree)中选择授权目录。
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);
startActivityForResult(intent, 42);
在 onActivityResult() 中，将用户选择的 Uri 传递给辅助类 DocumentFile。以下代码片段展示了如何列出选中目录下的文件和如何创建一个文件。
public void onActivityResult(int requestCode, int resultCode, Intent resultData) {
if (resultCode == RESULT_OK) {
Uri treeUri = resultData.getData();
DocumentFile pickedDir = DocumentFile.fromTreeUri(this, treeUri);
// List all existing files inside picked directory
for (DocumentFile file : pickedDir.listFiles()) {
Log.d(TAG, "Found file " + file.getName() + " with size " + file.length());
}
// Create a new file and write into it
DocumentFile newFile = pickedDir.createFile("text/plain", "My Novel");
OutputStream out = getContentResolver().openOutputStream(newFile.getUri());
out.write("A long time ago...".getBytes());
out.close();
}
}
由 DocumentFile.getUri() 返回的 Uri 使用非常灵活，可以与不同的 API 搭配使用。例如，你可以通过 Inetnt.setData() 将 Uri 分享出去，不过得将 Intent 的 flag 设置为 Intent.FLAG_GRANT_READ_URI_PERMISSION。
如何检测是否对某个文件/文件夹有访问权限
默认情况下，通过 Storage Access Framework 获取的 Uri 授权并不是永久的，设备重启后就会消失。不过，系统提供了相关的接口让授权永久化，如果需要的话可自行设置。在上述代码，你可以如此设置：
getContentResolver().takePersistableUriPermission(treeUri,
Intent.FLAG_GRANT_READ_URI_PERMISSION |
Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
之后，你就可以通过 ContentResolver.getPersistedUriPermissions() 来获取 APP 已经被永久授予权限的 Uri。如果不在需要某个 Uri 的权限，可以通过 ContentResolver.releasePersistableUriPermission() 来释放。
能否在 Kitkat 中使用
不能，因为该 API 是在 Lollipop 中添加的
能否知道有哪些 APP 拥有该权限
能。但是目前是没有 UI 界面的，你得通过 adb shell dumpsys activity providers 来获取。
在多用户的设备上授权该如何处理？
与多用户系统的其它功能一样，Uri 授权也是用户独立的。因此，同一个 APP 的 Uri 授权对每个用户是透明的。
授权是否可以被取消？
DocumentProvider 支持随时撤销授权。取消授权最常见的方法就是通过上面提到 ContentResolver.releasePersistableUriPermission() 。
当清除应用的数据时，应用相关的授权也都会被清除。
对于文件夹授权是否是递归授权的？
是的，通过 ACTION_OPEN_DOCUMENT_TREE 的 Intent 获取到授权之后，对该 Uri 下的所有文件都有读写权限。
授权是否支持多选操作？
从 Android 4.4(Kitkat) 起就支持了。您可以在启动 ACTION_OPEN_DOCUMENT Intent 时通过设置 EXTRA_ALLOW_MULTIPLE 来实现。您可以通过使用 Intent.setType() 或者 EXTRA_MIME_TYPES 来设置可选文件类型。具体参考：ACTION_OPEN_DOCUMENT
是否可以在模拟器上尝试新 API
可以的。如果你的 APP 只使用 Storage Access Framework 访问共享存储，你甚至不再需要 READ/WRITE_EXTERNAL_STORAGE 权限或者使用 android:maxSdkVersion 在较旧的版本上使用它们。
当用户替换 SD卡 时会发生什么？
当涉及物理介质时，底层媒体的 UUID（例如FAT序列号）总是被烧录到返回的 Uri 中。The system uses this to connect you to the media that the user originally selected, even if the user swaps the media around between multiple slots.(翻译不了)
如果用户替换了新的 SD卡，您需要重新申请 SD卡 授权。 由于系统会记住基于每个UUID的授权，如果用户以后重新插入，您将继续先前授予对原始卡的访问权限。
参考：磁盘序列号
