前一段時間有不少用戶反映客戶端無法在外置SD上緩存視頻，剛開始還懷疑是用戶的SD卡自身損壞導致的，后來經調查才發現原來是Google
從4.4版本開始，Android開始限制第三方應用在外置SD卡中公共目錄的寫權限，當你的應用需要在外置SD卡公共目錄中寫入應用數據時，就必須使用Google提供的SAF存儲訪問框架進行訪問。
雖然問題的根源找到了，但適配之路仍是非常的坎坷，特此記錄下來與君共勉。
SAF
Storage Access Framework (SAF)是google在Android4.4開始引入的一項存儲訪問框架，其意是為了當用戶需要訪問文檔，圖片或其他文件信息時提供一個統一簡單的訪問入口，可以方便高效的訪問不同文件內容提供商提供的文件信息。SAF共包含三個部分：
- DocumentProvider，一個可以管理文件內容的存儲服務，可以自定義管理文件的類型，目錄等。
- Client app，接收從DocumentProvider的返回的Uri進行文件操作，是完全自定義的。
- Picker，一個系統提供的可配置的文件選擇器，顯示所有DocumentProvider的內容，并授權用戶所選內容的讀寫權限，不可以自定義。
局限性
在使用SAF框架時除了需要兼容兩套文件操作，還需要適配和解決SAF自身的一些局限性問題。
- 對Android 4.4支持有限
google一開始在4.4+版本上引入的SAF并不是十分的完善。通過Picker UI獲取寫權限后，只能對已存在的文件執行刪除和內容修改操作，無法創建文件，也不能對文件目錄進行任何操作。原因主要在于：
- 在4.4版本上, SAF對外只提供了Intent.ACTION_OPEN_DOCUMENT (類似于ACTION_GET_CONTENT), 用戶只能從Picker UI中選擇文件而無法從Picker選擇目錄，從而導致第三方應用無法獲取到文件目錄的寫權限。直至從5.0開始SAF提供了Intent.ACTION_OPEN_DOCUMENT_TREE 后才支持了從Picker UI中選擇文件目錄。
- 在4.4版本上, SAF并不支持Intent.FLAG_GRANT_PREFIX_URI_PERMISSION即前綴匹配模式，若沒有該屬性，則每次授權都只能針對當前的選擇對象，就算對同一目錄下的文件進行寫操作，每個文件都需要進行一次權限申請，非常的繁瑣。
- Picker UI是系統提供的統一交互界面，不能進行任何自定義行為，同時第三方應用和DocumentProvider之間只能通過PickerUI進行通信，無法直接通信，所以就算自定義DocumentProvider也無法繞過Picker UI的操作限制。
-
權限獲取
從5.0開始，SAF提供了Intent.FLAG_GRANT_PREFIX_URI_PERMISSION前綴匹配模式，同時支持了Intent.ACTION_OPEN_DOCUMENT_TREE，這樣當第三方應用獲取了某一個文件目錄的操作權限后，對該目錄下的子目錄和文件都擁有了相同的操作權限。所以為了統一處理，第三方應用在使用SAF時必須引導用戶選擇在外置SD卡的根目錄進行權限授予，這樣第三方應用就獲取了整個外置SD卡的讀寫權限并且只需要授權一次。
但需要注意的是通過Intent.ACTION_OPEN_DOCUMENT，Picker UI返回的是一個DocumentUri， 而通過Intent.ACTION_OPEN_DOCUMENT_TREE，Picker UI返回的是一個TreeDocumentUri，而TreeDocumentUri只有才會被賦予Intent.FLAG_GRANT_PREFIX_URI_PERMISSION。
@Override
void onTaskFinished(Uri... uris) {
... ...
if (mState.action == ACTION_GET_CONTENT) {
intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
} else if (mState.action == ACTION_OPEN_TREE) {
intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION
| Intent.FLAG_GRANT_WRITE_URI_PERMISSION
|Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION
|Intent.FLAG_GRANT_PREFIX_URI_PERMISSION);
} else if (mState.action == ACTION_PICK_COPY_DESTINATION) {
... ...
} else {
intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION
| Intent.FLAG_GRANT_WRITE_URI_PERMISSION
|Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION);
}
... ...
}
為了可以直接利用Intent.FLAG_GRANT_PREFIX_URI_PERMISSION帶來的便利，SAF提供了一組特定類型的tree uri，使用規則相當于：
java content://provider的authority/tree/treeDocumentId/document/documentId 即 content://com.example/tree/12/document/24/children
其中treeDocumentId是之前已授權目錄的TreeDocumentUri中的documentId，document后的dcoumentId則是實際訪問的documentId, 因為已授權目錄的TreeDocumentUri是已知的，所以treeDocumentId可以通過DocumentsContract.getTreeDocumentId方法得到。 但對于需實際訪問的documentId，則仍需要我們自己去構建。
-
TreeDocumentFile
DocumentFile為DocumentProvider模仿一套和傳統File一樣的操作接口，便于兼容傳統File操作接口。其中TreeDocumentFile是專為TreeDocumentUri設計的，相當于是一個Directory，可以方便的對文件目錄進行相關操作。
并且TreeDocumentFile只能通過DocumentFile.fromTreeUri(Context context， Uri treeUri)方法來進行構造。源碼片段如下：// TreeDocumentFile.java TreeDocumentFile(DocumentFile parent, Context context, Uri uri) { super(parent); mContext = context; mUri = uri; } //DocumentFile.java public static DocumentFile fromTreeUri(Context context, Uri treeUri) { final int version = Build.VERSION.SDK_INT; if (version >= 21) { return new TreeDocumentFile(null, context, DocumentsContractApi21.prepareTreeUri(treeUri)); } else { return null; } //DocumentsContractApi21.java public static Uri prepareTreeUri(Uri treeUri) { return DocumentsContract.buildDocumentUriUsingTree(treeUri, DocumentsContract.getTreeDocumentId(treeUri)); } }需要注意上面的DocumentsContractApi21.prepareTreeUri方法，該方法在內部調用了DocumentsContract.buildDocumentUriUsingTree()方法，但它傳進去的documentId參數卻僅是treeUri的TreeDocumentId，這意味如果treeUri是根據上節權限獲取所述方式構建出的Uri，則得到TreeDocumentFile永遠只表示了外置SD卡的根目錄, 所以一般情況下TreeDocumentFile并不可用。
-
兩套File操作
考慮到android中主存儲是可以通過動態權限申請 ( 6.0以下在AndroidManifest中 ) 就可以獲取讀寫權限并且DocumengProvider獲取權限的要求略微復雜，所有這樣就不可避免的需要在代碼中維護兩套File操作(同一套api)，這樣在一定程度上增加了維護成本和構建成本。
同時由于TreeDocumentFile我們自己難以構造，而SingleDocumentFile對于Directory屬性的方法都不支持，所以有些常用的api就需要我們自己封裝了。- mkdirs
DocumengProvider雖然提供了createDocument方法，但需要注意的是調用createDocument方法的前提是父目錄必須存在，否在會創建失敗，所以我們封裝mkdirs時需要從根目錄開始層層判斷父目錄是否存在，這一點尤為的麻煩。
@Override public String createDocument(String docId, String mimeType, String displayName) throws FileNotFoundException { displayName = FileUtils.buildValidFatFilename(displayName); final File parent = getFileForDocId(docId); if (!parent.isDirectory()) { throw new IllegalArgumentException("Parent document isn't a directory"); } ... ... }- renameTo
DocumengProvider雖然直接提供了renameDocument的方法，但renameTo的對象只能在同級目錄下，不能更換父目錄，因為輸入參數只有displayName，這個是和File的rename不一樣的，使用時需要格外的注意。
@Override public String renameDocument(String docId, String displayName) throws FileNotFoundException { displayName = FileUtils.buildValidFatFilename(displayName); final File before = getFileForDocId(docId); final File after = FileUtils.buildUniqueFile(before.getParentFile(), displayName); if (!before.renameTo(after)) { throw new IllegalStateException("Failed to rename to " + after); } ... ... } - mkdirs
-
國產ROM
國產ROM有時候會修改System Picker UI的交互，越改越難用，典型的就是華為的xxxROM，把原生系統的選擇按鈕改成了全選，不明所以。enter image description here國產ROM有時候還有修改SAF存儲框架，在華為xxx機型上居然不需要通過SAF申請任何權限，僅通過存儲權限申請就是可以在外置SD卡的任意目錄讀寫，而有時在某系機型上會突然性的出現在外置SD卡的默認包名下沒有寫權限，只能通過SAF申請權限后才能進行正常寫入。
所以這些都是我們在適配時都需要注意的，除了做好SAF權限授權引導，還是盡量避免申請SAF權限，畢竟操作還是十分繁瑣的。
歡迎查看 個人博客.
