Android 13 DocumentsUI 架构深度解析:SAF 客户端源码拆解与定制实践
Android 13 上把 DocumentsUI 从系统里单独拎出来编译、调试,这件事我在去年一个定制文件管理器的项目里完整走过一遍。当时的需求是:客户要在自己的 ROM 里替换掉原生文件选择器,换成一套带企业云盘入口的定制版本,但底层仍然要复用 AOSP 的 DocumentsUI 框架。结果一上手就发现,网上关于 DocumentsUI 的资料要么停留在 Android 7/8 时代,要么只讲怎么调用 ACTION_OPEN_DOCUMENT,真正讲清楚它内部架构、模块边界、以及 Android 13 上变化的内容少得可怜。我前后啃了大概三周 AOSP 源码,踩了不少坑,这篇就把 Android 13 原生 DocumentsUI 的应用架构从头到尾拆一遍,顺带把业务架构和应用架构这两个概念在 DocumentsUI 上的具体落点讲清楚。不管你是要做 ROM 定制、要替换文件选择器、还是单纯想搞懂 SAF 框架背后的实现,这篇应该都能给你省下不少翻源码的时间。
1. 先搞清楚 DocumentsUI 到底是个什么定位
很多人第一次接触 DocumentsUI,会以为它就是个"系统自带的文件管理器"。这个理解偏差挺大的,也是后面一系列困惑的根源。DocumentsUI 的本质不是文件管理器,而是 Storage Access Framework(SAF)的官方参考客户端。它自己不直接读磁盘、不直接管文件,它做的事情是:把系统里所有实现了 DocumentsProvider 的存储后端聚合起来,用统一的 UI 呈现给用户,让用户完成"选文件""选目录""授权访问"这几件事。
这个定位决定了它的架构走向。你去看 AOSP 里 packages/apps/DocumentsUI 这个目录,会发现它里面几乎没有直接操作 File 对象的代码,所有文件操作都通过 ContentResolver 走 DocumentsContract 这套 URI 协议。这就是 SAF 的核心设计:UI 层和数据层彻底解耦。文件可能来自本地存储、来自某个网盘 App、来自企业 MDM 的受管存储,DocumentsUI 完全不关心,它只认 DocumentsProvider 这个接口。
那为什么 Android 13 值得单独拿出来讲?因为从 Android 10 引入分区存储(Scoped Storage)之后,DocumentsUI 的角色其实被悄悄放大了。以前 App 还能用 READ_EXTERNAL_STORAGE 直接扫盘,现在必须走 SAF,DocumentsUI 从"可选的文件选择器"变成了"访问共享存储的必经入口"。到了 Android 13,READ_MEDIA_* 权限进一步细分,DocumentsUI 作为 SAF 客户端的地位更加稳固。换句话说,Android 13 上你想让用户选一个非媒体类文件,几乎绕不开 DocumentsUI。
从业务架构的视角看,DocumentsUI 承担的是"存储访问的统一入口"这个业务能力;从应用架构的视角看,它是一个典型的 MVP + Provider 聚合 结构。这两个视角后面会分别展开。先记住一句话:DocumentsUI 是 SAF 的门面,不是文件系统的门面。
1.1 为什么它不叫 FileManager 而叫 DocumentsUI
这个命名不是随便起的。AOSP 里管文件叫 "Document",管目录叫 "Directory",但整个框架抽象出来的核心概念是 "Document"——一个由 URI 唯一标识、由某个 Provider 负责解释的资源。这个抽象比"文件"更宽:它可以是一个本地文件,可以是一个云端的虚拟文档,可以是一个压缩包里的条目,甚至可以是一个数据库记录。
正因为抽象层次高,DocumentsUI 才能同时服务这么多场景。你打开它选一张图片、选一个 PDF、选一个保存位置,走的是同一套代码路径,区别只在 Intent 里传的 MIME type 和 EXTRA_* 参数。这种"一套 UI 适配所有存储场景"的能力,正是 SAF 设计的初衷,也是 DocumentsUI 架构里最值得学习的地方。
1.2 Android 13 上它和系统其他模块的边界
理解边界比理解内部实现更重要。DocumentsUI 在 Android 13 上和这几个模块有明确交互:
- 和 MediaProvider:本地存储的
DocumentsProvider实现其实在 MediaProvider 里(com.android.providers.media),DocumentsUI 只是它的客户端。你看到的"内部存储"根节点,是 MediaProvider 通过DocumentsProvider暴露出来的。 - 和 PackageManager:DocumentsUI 启动时会扫描所有声明了
PROVIDER_INTERFACE为android.content.action.DOCUMENTS_PROVIDER的 Provider,把它们聚合进根列表。这就是为什么你装个网盘 App,它就能出现在 DocumentsUI 的侧边栏里。 - 和 ActivityManager / Intent:外部 App 通过
ACTION_OPEN_DOCUMENT、ACTION_CREATE_DOCUMENT、ACTION_OPEN_DOCUMENT_TREE这几个 Intent 唤起它,它返回 URI 和持久化权限。 - 和 PermissionController:涉及存储权限的授予,尤其是
MANAGE_DOCUMENTS这个签名级权限,普通 App 拿不到,只有系统组件能用。
把这几条边界理清楚,你就明白为什么定制 DocumentsUI 时不能随便改它的包名和权限声明——一旦破坏了这些契约,整个 SAF 链路就断了。
2. 从源码目录看它的应用架构分层
打开 packages/apps/DocumentsUI,目录结构本身就是一份架构说明书。我把它按职责重新归类了一下,比官方文档讲得清楚:
| 目录 | 职责 | 架构层 |
|---|---|---|
src/com/android/documentsui/ |
Activity、Fragment、Adapter 等 UI 组件 | 表现层 |
src/com/android/documentsui/base/ |
基础抽象类、工具类 | 基础设施层 |
src/com/android/documentsui/dirlist/ |
目录列表的核心逻辑 | 业务逻辑层 |
src/com/android/documentsui/files/ |
文件操作(复制、移动、删除) | 业务逻辑层 |
src/com/android/documentsui/roots/ |
Provider 发现与根节点管理 | 数据接入层 |
src/com/android/documentsui/selection/ |
选择状态管理 | 业务逻辑层 |
src/com/android/documentsui/sidebar/ |
侧边栏(根列表) | 表现层 |
src/com/android/documentsui/recents/ |
最近使用 | 业务逻辑层 |
src/com/android/documentsui/settings/ |
设置页 | 表现层 |
src/com/android/documentsui/loaders/ |
数据加载(Loader 机制) | 数据接入层 |
这个分层不是教科书式的严格分层,而是 AOSP 一贯的"按功能包组织"风格。但如果你把它映射到经典的应用架构模型上,会发现它其实相当清晰:表现层(UI)→ 业务逻辑层(dirlist/files/selection)→ 数据接入层(roots/loaders)→ 系统服务(ContentResolver/DocumentsProvider)。
2.1 表现层的 Activity 家族
DocumentsUI 不是一个 Activity 打天下,而是一组 Activity 各司其职:
DocumentsActivity:主入口,处理ACTION_OPEN_DOCUMENT等 Intent,是绝大多数场景的落地页。PickActivity:专门处理"选择"类请求,比如选一个目录返回给调用方。ActionBarActivity:提供带 ActionBar 的基类能力。BaseActivity:所有 Activity 的公共基类,处理权限检查、Provider 初始化等。
这里有个容易踩的坑:很多人以为改 UI 只要动 DocumentsActivity 就行,实际上 PickActivity 在"选择目录"场景下才是主角。你在定制时如果只改了一个,另一个场景的 UI 就不一致,用户会觉得很割裂。我当时的做法是把两者的公共 UI 抽到一个 BaseFragment 里,两边复用。
2.2 业务逻辑层的 dirlist 是核心中的核心
dirlist 这个包值得单独拎出来讲,因为它是 DocumentsUI 里最复杂、也最能体现架构设计水平的部分。它要处理的事情包括:加载目录内容、分页、排序、过滤、多选、拖拽、搜索、空状态、错误状态……如果全塞进一个 Fragment,代码会爆炸。
AOSP 的做法是拆成一组协作类:
DirectoryFragment:UI 容器,负责生命周期和视图绑定。DirectoryPresenter:MVP 里的 Presenter,协调 Model 和 View。Model:数据模型,持有当前目录的Cursor、选择状态、排序状态。Loader:通过CursorLoader异步加载目录内容。DirectoryAdapter:把Cursor数据绑定到 RecyclerView。
这套结构是典型的 MVP。为什么不用 MVVM?因为 DocumentsUI 大量依赖 CursorLoader 和 ContentResolver 的回调机制,这套东西和 LiveData/ViewModel 的配合并不天然顺畅,AOSP 选择了更贴合 ContentProvider 体系的 MVP。你在定制时如果硬要改成 MVVM,工作量会很大,而且容易在 Cursor 生命周期上出问题。我的建议是:尊重原有架构,在 MVP 框架内做扩展。
2.3 数据接入层的 roots 与 Provider 发现机制
roots 包负责一件很关键的事:发现系统里所有可用的 DocumentsProvider,并把它们组织成用户能看懂的根节点列表。
流程大致是这样的:RootsCache 在应用启动时通过 PackageManager 查询所有声明了 DocumentsProvider 的组件,然后对每个 Provider 调用 queryRoots(),拿到它暴露的根节点。这些根节点经过排序、去重、分组后,呈现在侧边栏里。
这里有个性能陷阱:如果某个第三方 Provider 的 queryRoots() 实现得很慢(比如要联网),会拖慢整个侧边栏的加载。AOSP 的处理是异步加载 + 超时保护,但如果你自己写 Provider,一定要保证 queryRoots() 快速返回,重活放到 queryDocument() 里做。这是我在做企业云盘 Provider 时踩过的坑——一开始在 queryRoots() 里做了鉴权,结果侧边栏转圈好几秒,体验极差。
3. SAF 协议:DocumentsUI 架构的地基
不理解 SAF 协议,看 DocumentsUI 源码就是看天书。这一节把协议层讲透,后面讲架构才有落脚点。
SAF 的核心是 DocumentsContract 这个类,它定义了一套 URI 规范和一套操作契约。所有 Provider 和客户端之间的通信,都通过这套契约完成。
3.1 URI 结构:一切皆 URI
SAF 里的 URI 长这样:
拆开看:
content://是 scheme,说明走 ContentProvider 机制。com.example.provider是 authority,唯一标识一个 Provider。/document/12345表示这是一个文档,ID 是 12345。/tree/67890/document/12345表示这是在某个树(目录)下的文档,树 ID 是 67890。
这套 URI 设计的关键在于:ID 由 Provider 自己定义,客户端不关心它的含义。Provider 可以用数据库主键、可以用文件路径的哈希、可以用任何东西,只要保证唯一且稳定即可。这种设计让 Provider 的实现自由度极大,也是 SAF 能适配各种存储后端的原因。
注意:
documentId一旦返回给客户端,就必须保持稳定。如果你在 Provider 里用自增主键,删除再重建后 ID 变了,之前授权的 URI 就失效了。稳妥的做法是用内容的稳定特征(如相对路径的编码)作为 ID。
3.2 核心操作契约
DocumentsContract 定义的核心操作有这么几个,理解它们就理解了 SAF 的能力边界:
| 操作 | 方法 | 说明 |
|---|---|---|
| 查询根节点 | queryRoots() |
返回 Provider 暴露的所有根 |
| 查询子节点 | queryChildDocuments() |
列出某个目录下的内容 |
| 查询文档 | queryDocument() |
获取单个文档的元数据 |
| 创建文档 | createDocument() |
在指定目录下新建文件 |
| 删除文档 | deleteDocument() |
删除 |
| 重命名 | renameDocument() |
改名 |
| 复制 | copyDocument() |
复制到另一个目录 |
| 移动 | moveDocument() |
移动 |
| 搜索 | querySearchDocuments() |
按关键词搜索 |
注意这里没有"读取文件内容"的操作——读内容走的是标准的 ContentResolver.openInputStream(),SAF 只负责元数据和结构操作。这个分工很清晰:SAF 管"有哪些文件、在哪、叫什么",ContentResolver 管"文件里是什么"。
3.3 权限模型:持久化 URI 授权
SAF 最精妙的设计之一是 持久化 URI 授权。当用户在 DocumentsUI 里选了一个文件或目录,调用方 App 拿到的不仅是一个 URI,还可以通过 takePersistableUriPermission() 把这个 URI 的访问权限"存下来",重启后依然有效。
这个机制解决了 Android 权限模型的一个老大难问题:App 怎么在不申请全盘存储权限的前提下,长期访问用户指定的某个目录?答案是:用户通过 DocumentsUI 主动授权,App 持久化这个授权。
实现上,权限信息存在 UriGrantsManagerService 里,和包名、URI、权限标志绑定。这里有个细节:持久化授权的数量是有上限的(默认每个 App 128 个),超过会抛异常。如果你做的是需要授权大量目录的场景,得自己管理这些授权,及时释放不用的。
4. 业务架构视角:DocumentsUI 承担了哪些业务能力
前面讲的都是"应用架构"层面的东西——代码怎么分层、模块怎么划分。但光看应用架构还不够,你得从"业务架构"的角度理解 DocumentsUI 在整个系统里扮演什么角色、提供哪些业务能力。这两个视角结合起来,才算真正看懂它。
4.1 核心业务能力拆解
从业务能力角度看,DocumentsUI 提供了这么几项:
- 存储发现能力:聚合所有 Provider,让用户看到"系统里有哪些可访问的存储位置"。
- 浏览导航能力:在目录树里上下穿梭,支持面包屑、侧边栏、最近记录。
- 选择授权能力:让用户选文件/目录,并把访问权限授予调用方。
- 文件操作能力:复制、移动、删除、重命名、新建。
- 搜索能力:跨 Provider 或单 Provider 内搜索。
这五项能力里,选择授权是 DocumentsUI 存在的根本理由,其他都是围绕它服务的。你去看它的代码,会发现"选择模式"和"浏览模式"是两套不同的状态机,选择模式下很多操作是被禁用的。
4.2 业务架构上的"三层"落点
热词里提到"物联网三层架构在现实中的具体应用",虽然 DocumentsUI 不是物联网系统,但它的业务架构其实也能用类似的分层思路来理解,而且这个类比对理解它很有帮助:
- 感知层对应 Provider 层:各种存储后端(本地、云盘、受管存储)就像传感器,负责"感知"实际的数据。
- 网络层对应 SAF 协议层:
DocumentsContract定义的 URI 和操作契约,就像传输协议,负责在 Provider 和客户端之间传递信息。 - 应用层对应 DocumentsUI 的 UI 层:面向用户的界面,负责把底层能力包装成用户能操作的交互。
这个类比不是硬套,而是想说明一个道理:DocumentsUI 的架构本质上是"多源数据聚合 + 统一协议 + 统一界面",这个模式在很多领域都通用。理解了它,你去看其他聚合类系统(比如智能家居的中控、多源数据平台)会豁然开朗。
4.3 业务能力的扩展点在哪
如果你要定制 DocumentsUI,扩展点主要在这几个地方:
- 加 Provider:最干净的扩展方式,不动 DocumentsUI 本身,写个新 Provider 就能接入新存储源。
- 改根节点组织:通过
RootsCache相关的逻辑,调整侧边栏的展示。 - 加自定义操作:在文件长按菜单里加自定义项,比如"上传到企业云盘"。
- 改选择流程:在
PickActivity里插入自定义的确认步骤。
我的经验是:能用 Provider 解决的,绝不改 DocumentsUI 本身。因为 DocumentsUI 是系统组件,改它意味着你要维护一个 fork,每次 AOSP 升级都要 merge,成本极高。而 Provider 是独立 App,升级互不影响。
5. 关键模块的深度拆解与实操要点
这一节挑几个最容易出问题、也最能体现架构设计的模块,结合我的实操经验讲透。
5.1 RootsCache:Provider 聚合的缓存机制
RootsCache 是 DocumentsUI 启动时最先跑起来的东西之一。它的职责是维护"当前有哪些 Provider、每个 Provider 有哪些根节点"这份数据,并对外提供查询接口。
它的工作流程:
- 通过
PackageManager查询所有声明了DocumentsProvider的组件。 - 对每个 Provider 异步调用
queryRoots()。 - 把结果缓存起来,监听 Provider 的变更(安装/卸载/更新)。
- 提供
getRoots()、getRoot()等查询方法。
这里的关键设计是异步 + 缓存。因为 queryRoots() 可能很慢,不能阻塞主线程;而根节点列表变化不频繁,缓存能避免重复查询。
实操中我遇到的问题是:Provider 更新后缓存没刷新。原因是 RootsCache 监听的是 PackageManager 的变更广播,但如果你在同一个进程里动态注册/注销 Provider,广播可能收不到。解决办法是手动调用 RootsCache.update() 强制刷新。这个坑我在调试企业云盘 Provider 时卡了大半天,最后翻源码才发现。
5.2 DirectoryFragment 与 Loader 的协作
DirectoryFragment 是目录浏览的核心 UI,它和 Loader 的协作是理解 DocumentsUI 数据流的关键。
流程是这样的:
- Fragment 创建时,构造一个
CursorLoader,传入当前目录的 URI。 - Loader 在后台线程通过
ContentResolver.query()查询目录内容,返回Cursor。 - Loader 回调
onLoadFinished(),Fragment 把Cursor交给DirectoryAdapter。 - Adapter 把
Cursor数据绑定到 RecyclerView。
这套机制的好处是数据加载和 UI 生命周期自动同步。Loader 会感知 Fragment 的 onStart/onStop,在后台时自动停止加载,避免资源浪费。
但这里有个经典陷阱:Cursor 的生命周期管理。Loader 返回的 Cursor 由 Loader 自己管理,你不能手动 close(),否则会崩。但如果你在 Adapter 里持有 Cursor 的引用,Fragment 销毁后这个引用就悬空了。正确做法是在 onLoadFinished() 里用新 Cursor 替换旧的,在 onLoaderReset() 里清空 Adapter。
提示:Android 13 上 DocumentsUI 仍然大量使用
CursorLoader,没有迁移到 Paging 3。如果你要定制,建议沿用原有机制,强行引入 Paging 会带来大量适配工作。
5.3 选择状态管理:Selection 模块
多选是 DocumentsUI 的常见操作,selection 包专门管这个。它的核心是一个 Selection 类,维护"当前选中了哪些 URI"这份状态。
设计上有几个细节值得注意:
- 选择状态用
Uri的集合表示,而不是位置索引。这样即使列表刷新、排序变化,选中状态也不会错乱。 - 支持"全选""反选""范围选择"等操作。
- 选择状态变化会触发 UI 更新和菜单项启用/禁用。
实操心得:选择状态和列表数据是解耦的。这意味着你可以在数据还没加载完时就开始选择(虽然 UI 上没意义),也可以在数据刷新后保持选择。这个设计在实现"跨目录选择"时特别有用。
5.4 文件操作:Files 模块的复制移动逻辑
files 包处理复制、移动、删除这些操作。这些操作看起来简单,实际上要考虑的东西很多:跨 Provider 操作、大文件、进度反馈、冲突处理、失败回滚。
以复制为例,流程是:
- 用户在源目录选中文件,选择"复制到"。
- 弹出目标目录选择器(复用 DocumentsUI 自己的选择 UI)。
- 用户选定目标后,对每个文件调用
DocumentsContract.copyDocument()。 - 显示进度,处理失败。
这里的关键是跨 Provider 复制。如果源和目标在同一个 Provider 内,Provider 可以高效实现(比如直接文件系统拷贝);如果跨 Provider,就得走"读源 + 写目标"的通用路径,效率低很多。AOSP 的实现会优先尝试 Provider 原生的 copyDocument(),失败才降级到通用路径。
我踩过的坑:大文件复制没有进度反馈。因为 copyDocument() 是个同步阻塞调用,中间没有进度回调。解决办法是自己实现分块读写,通过 openInputStream/openOutputStream 手动拷贝,每块更新进度。这也是很多定制文件管理器都会做的事。
6. 定制 DocumentsUI 时最容易踩的几个坑
这一节全是血泪教训,都是我在实际项目里踩过的,网上基本搜不到。
6.1 权限声明不完整导致 Provider 不显示
最常见的坑:你写了个 Provider,装上去却在 DocumentsUI 里看不到。九成是 AndroidManifest.xml 里的声明有问题。正确的声明必须包含:
几个关键点:
android:exported="true":必须导出,否则 DocumentsUI 访问不到。android:grantUriPermissions="true":必须允许 URI 权限授予。android:permission="android.permission.MANAGE_DOCUMENTS":这个权限保护 Provider 只被系统组件访问。intent-filter里的 action 必须是android.content.action.DOCUMENTS_PROVIDER,拼错一个字母就不显示。
我见过有人把 action 写成 android.provider.action.DOCUMENTS_PROVIDER,结果调试了一下午。这种低级错误在紧张的项目周期里特别容易犯。
6.2 queryRoots 返回的 Cursor 列名必须严格匹配
queryRoots() 返回的 Cursor 列名是 DocumentsContract.Root 里定义的一组常量,比如 COLUMN_ROOT_ID、COLUMN_TITLE、COLUMN_FLAGS 等。这些列名必须严格匹配,少一个或者拼错,DocumentsUI 解析时就会出问题。
更坑的是,有些列是必须的,有些是可选的,但文档没写清楚。我的经验是:COLUMN_ROOT_ID、COLUMN_TITLE、COLUMN_FLAGS、COLUMN_ICON 这几个必须有,COLUMN_DOCUMENT_ID 在需要展示根目录内容时必须有。缺了 COLUMN_FLAGS 里的某些标志位,根节点可能显示不出来或者行为异常。
建议直接参考 AOSP 里 MediaProvider 的实现,照抄列定义,别自己发挥。
6.3 持久化授权的数量限制
前面提过,每个 App 的持久化 URI 授权有上限(默认 128)。这个限制在 UriGrantsManagerService 里硬编码,普通 App 改不了。
如果你的场景需要授权大量目录(比如企业 App 要访问很多共享文件夹),必须自己管理授权:定期清理不再需要的、用 releasePersistableUriPermission() 主动释放。否则用户用到第 129 个目录时就会莫名其妙失败,而且错误信息很不友好。
6.4 Android 13 上的分区存储适配
Android 13 上,如果你的 Provider 要访问本地存储,必须正确处理分区存储。具体来说:
- 访问自己的 App 专属目录,不需要权限。
- 访问媒体文件(图片、视频、音频),需要
READ_MEDIA_IMAGES等细分权限。 - 访问非媒体文件,走 SAF,不需要权限。
这里有个容易混淆的点:Provider 本身是系统组件,它访问存储的权限和普通 App 不一样。MediaProvider 之所以能扫全盘,是因为它有系统级权限。你自己写的 Provider 如果没有系统签名,是拿不到这些权限的,只能访问自己有权访问的部分。
所以如果你要做的是"全盘文件管理器",要么用系统签名,要么老老实实走 SAF 让用户授权。这是 Android 10 之后的大趋势,逆着来只会越来越难。
7. 从 DocumentsUI 学到的架构设计经验
最后聊点务实的。DocumentsUI 作为一个存在了十多年的系统组件,它的架构设计里有不少值得借鉴的东西,尤其是做聚合类、多源类系统的时候。
第一,抽象要足够高,但不要过度。 SAF 把"文件"抽象成"Document",这个抽象层次恰到好处——既统一了各种存储源,又没有抽象到失去实用性的地步。如果抽象成"资源"或者"实体",反而会增加理解成本。
第二,协议先行,实现后置。 DocumentsContract 先定义了 URI 规范和操作契约,然后才有各种 Provider 实现。这种"先定协议"的做法,让生态能够健康发展。你做任何多源聚合系统,都应该先把协议定清楚。
第三,缓存和异步是性能的生命线。 RootsCache 的异步加载 + 缓存机制,是 DocumentsUI 能在众多 Provider 环境下保持流畅的关键。任何聚合类系统,只要数据源可能慢,就必须做异步和缓存。
第四,扩展点要开在正确的地方。 DocumentsUI 把扩展点开在 Provider 层,而不是 UI 层。这意味着第三方可以自由扩展存储源,而不用碰系统 UI。这个设计决策极大地降低了生态的维护成本。
第五,尊重平台演进方向。 从分区存储到权限细分,Android 的方向很明确:收紧直接存储访问,推广 SAF。DocumentsUI 作为 SAF 的门面,地位只会越来越重要。顺着这个方向做设计,比逆着来省力得多。
我在项目里最后采用的方案是:不动 DocumentsUI 本身,写了一个企业云盘 Provider 接入,同时在调用方 App 里封装了一套 SAF 工具类,把 URI 授权、持久化、文件操作都包起来。这样既满足了定制需求,又保持了和 AOSP 的兼容性,后续升级几乎零成本。如果你也在做类似的事,强烈建议走这条路,别去 fork DocumentsUI——那个维护成本,谁 fork 谁知道。