Android API Guide
Android 4.4 引入了存储访问框架Storage Access Framework(SAF),云或本地存储服务可以实现DocumentProvider来分装他们的服务以便加入到该生态系统中。
SAF包含了
Document Provider, Android 包含几个内置的DocumentsProvider,注入下载Downloads, Images, Videos.
Client App: 一个自定义的App,可发送ACTION_OPEN_DOCUMENT或者ACTION_CREATE_DOCUMENT,接收返回的文件。
Picker: 一个系统UI, 允许用户访问所有document providers 满足client app的搜索条件的。
Overview
架构图
- 以Root开始,指向单一节点,然后改单一节点再扇形展开。每个Root都有一个独一无二的COLUMN_ROOT_ID, 并且指向一个document或者directory, 代表了该Root下的内容。
- 在每个root下是一个single document, 该document指向1 to N个documents, 这下面的每个再指向1 to N个documents。
- 每个文件或者目录 都有COLUMN_DOCUMENT_ID, 该ID必须是独一无二的,且在issue后不可修改的。
- documents 可以是可打开的文件,也可是目录。
- 每个document 可以具有不同的能力,由COLUMN_FLAGS指定。例如:FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE, and FLAG_SUPPORTS_THUMBNAIL. 此外,COLUMN_DOCUMENT_ID可以出现在多个目录下。
Control Flow
document provider 的数据模型是基于传统的文件架构。但是,物理上,你可以随意存储,只要可以被DocumentProvider API访问。
下图显示了一个Photo App如何使用SAF访问图片
注意到:
1. Client and Provider 不直接交互。
2. 当客户端发起一个Intent(ACTION_OPEN_DOCUMENT or ACTION_CREATE_DOCUMENT), 可能包括一些filters
3. 一旦Intent发出, the system picker 就会到每个注册的provider,并显示匹配结果。
4. Picker提供一个标准的接口访问文件。
Writing a Client App
在Android 4.3之前,使用ACTION_PICK或者ACTION_GET_CONTENT 获得文件,对于后者是仅copy一份文件。
在Android 4.4及更高版本,将可使用ACTION_OPEN_DOCUMENT来获取文件,是直接使用源文件。
Search for documents
发起搜索图片请求
private static final int READ_REQUEST_CODE = 42;
...
/**
* Fires an intent to spin up the "file chooser" UI and select an image.
*/
public void performFileSearch() {
// ACTION_OPEN_DOCUMENT is the intent to choose a file via the system's file
// browser.
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
// Filter to only show results that can be "opened", such as a
// file (as opposed to a list of contacts or timezones)
intent.addCategory(Intent.CATEGORY_OPENABLE);
// Filter to show only images, using the image MIME data type.