documentsUI源码分析

documentsUI源码分析

本文基于Android 6.0的源码，来分析documentsUI模块。

原本基于7.1源码看了两天，但是Android 7.1与6.0中documentsUI模块差异很大，且更加复杂，因此重新基于6.0的源码分析。

documentsUI是什么？

documentsUI是Android系统提供的一个文件选择器，类似于Windows系统中点击“打开”按钮弹出的文件选择框，有人称documentsUI为文件管理器，这是不准确的。

documentsUI是Android系统中存储访问框架(Storage Access Framework，SAF)的一部分。

Android 4.4（API 级别 19）引入了存储访问框架 (SAF)。SAF 让用户能够在其所有首选文档存储提供程序中方便地浏览并打开文档、图像以及其他文件。 用户可以通过易用的标准UI，以统一方式在所有应用和提供程序中浏览文件和访问最近使用的文件。

documentsUI的清单文件中只有一个Activity，且没有带category.LAUNCHER的属性，因此Launcher桌面上并没有图标，但是进入documentsUI的入口很多，如桌面上的下载应用、短信中的添加附件、浏览器中上传图片等。

documentsUI清单文件中的activity如下：

<activity
            android:name=".DocumentsActivity"
            android:theme="@style/DocumentsTheme"
            android:icon="@drawable/ic_doc_text">
            <intent-==filter==>
                <action android:name="android.intent.action.OPEN_DOCUMENT" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.OPENABLE" />
                <data android:mimeType="*/*" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.CREATE_DOCUMENT" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.OPENABLE" />
                <data android:mimeType="*/*" />
            </intent-filter>
            <intent-filter android:priority="100">
                <action android:name="android.intent.action.GET_CONTENT" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.OPENABLE" />
                <data android:mimeType="*/*" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.OPEN_DOCUMENT_TREE" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.provider.action.MANAGE_ROOT" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:mimeType="vnd.android.document/root" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.provider.action.BROWSE_DOCUMENT_ROOT" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:mimeType="vnd.android.document/root" />
            </intent-filter>
        </activity>

存储访问框架SAF

在介绍documentUI之前，需要介绍存储访问框架，在Android 4.4（API 级别 19），Google引入了存储访问框架 (SAF)，让用户能够在其所有首选文档存储提供程序中方便地浏览并打开文档、图像以及其他文件。 用户可以通过易用的标准 UI，以统一方式在所有应用和提供程序中浏览文件和访问最近使用的文件。

云存储服务或本地存储服务可以通过实现封装其服务的 DocumentsProvider 参与此生态系统。只需几行代码，便可将需要访问提供程序文档的客户端应用与 SAF 集成。

SAF 包括以下内容：

• 文档提供程序 — 一种内容提供程序，允许存储服务（如 Google Drive）显示其管理的文件。 文档提供程序作为 DocumentsProvider 类的子类实现。文档提供程序的架构基于传统文件层次结构，但其实际数据存储方式由您决定。Android 平台包括若干内置文档提供程序，如 Downloads、Images 和 Videos。

• 客户端应用 — 一种自定义应用，它调用 ACTION_OPEN_DOCUMENT 和/或 ACTION_CREATE_DOCUMENT Intent 并接收文档提供程序返回的文件；

• 选取器 — 一种系统 UI，允许用户访问所有满足客户端应用搜索条件的文档提供程序内的文档。

控制流

文档提供程序数据模型基于传统文件层次结构。 通过DocumentsProvider API访问数据，可以按照自己喜好的任何方式存储数据。例如，可以使用基于标记的云存储来存储数据。

如上图所示，在 SAF 中，提供程序和客户端并不直接交互。

• 客户端请求与文件交互（即读取、编辑、创建或删除文件）的权限；

• 交互在应用（在本示例中为照片应用）触发 Intent ACTION_OPEN_DOCUMENT 或ACTION_CREATE_DOCUMENT 后开始。Intent 可能包括进一步细化条件的过滤器 — 例如，“为我提供所有 MIME 类型为‘图像’的可打开文件”；

• Intent 触发后，系统选取器将检索每个已注册的提供程序，并向用户显示匹配的内容根目录；

• 选取器会为用户提供一个标准的文档访问界面，但底层文档提供程序可能与其差异很大。 例如，图 2 显示了一个 Google Drive 提供程序、一个 USB 提供程序和一个云提供程序。

客户端应用

编写一个客户端应用，调用documentsUI选择文件。

    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.
    intent.setType("image/*");
    
    startActivityForResult(intent, READ_REQUEST_CODE);

通过Intent.ACTION_OPEN_DOCUMENT，documentsUI将响应该意图，选择文件后，在返回结果中提取UR