Android 13 DocumentsUI 源码解析:SAF 前端架构与定制实战
Android 13 上把 DocumentsUI 从系统镜像里单独拎出来编译、调试、改需求,是这两年做定制 ROM 和文件管理类应用的同学绕不开的一件事。它表面上只是「文件选择器」,实际上承担了存储访问框架(SAF)的整套前端交互:从三方应用调起 ACTION_OPEN_DOCUMENT,到用户点选目录、授权持久化 URI,再到 MTP、下载、最近文件这些入口的聚合,全都压在这一个 APK 里。很多人第一次拿到源码会懵——它既不是普通的单 Activity 应用,也不是标准的 MVVM 分层,而是带着 AOSP 特有的 Loader、Provider、DialogFragment 混搭风格。这篇就把我在 Android 13 源码树里反复翻 DocumentsUI 的收获整理出来,从模块边界、核心组件、数据流到实际改造时踩过的坑,尽量讲透。适合正在做 ROM 定制、系统应用二次开发,或者单纯想搞懂 SAF 前端怎么运转的 Android 工程师。
1. 先搞清楚 DocumentsUI 到底管了多大一摊事
1.1 它在系统里的真实定位
很多人以为 DocumentsUI 就是「文件管理器」,这个认知偏差会直接导致改造方向跑偏。准确说,它是 SAF(Storage Access Framework)的官方前端实现,包名是 com.android.documentsui,在 Android 13 里源码路径位于 packages/apps/DocumentsUI。它自己不直接读磁盘,所有文件数据都来自实现了 DocumentsProvider 的各类 Provider——比如 ExternalStorageProvider(内部存储和 SD 卡)、DownloadStorageProvider(下载)、MediaDocumentsProvider(图片视频音频)、MtpDocumentsProvider(连接电脑时的 MTP),以及三方 App 自己注册的 Provider。
理解这一点非常关键:DocumentsUI 是一个纯 UI 壳 + 交互协调层。它通过 ContentResolver 去查询 Provider 暴露的 DocumentsContract 接口,拿到 Cursor 后渲染列表。所以你在 DocumentsUI 里看到的每一个文件条目,背后都是一次跨进程的 Provider 查询。这也解释了为什么它大量使用 Loader 而不是直接 query()——因为跨进程查询慢且需要异步、需要生命周期感知、需要在数据变化时自动刷新。
从业务架构角度看,它属于典型的「前端聚合层」:向下屏蔽了不同 Provider 的差异,向上给三方应用提供统一的文件选择体验。这跟物联网三层架构里「平台层聚合设备差异、应用层统一调用」的思路其实是一回事,只不过这里聚合的是存储源,不是传感器。
1.2 模块划分与依赖关系
Android 13 的 DocumentsUI 在 Gradle 层面被拆成了几个模块,这是它和很多系统应用不一样的地方:
| 模块 | 职责 | 关键产物 |
|---|---|---|
app |
主应用,Activity、Fragment、Adapter 全在这 | DocumentsUI.apk |
libs |
公共工具、Provider 交互封装 | 静态库 |
tests |
单元测试与集成测试 | 测试 APK |
prebuilts |
预编译依赖 | — |
主模块内部又按功能包划分:com.android.documentsui(根,放 Activity 和核心逻辑)、base(DialogFragment 基类、状态管理)、dir(目录列表页)、recents(最近文件)、search(搜索)、sidepanel(侧边栏 Roots 列表)、picker(选择模式)、files(文件列表项)、model(数据模型)、selection(多选管理)。
我建议第一次读源码的人从 BaseActivity 和 DocumentsActivity 入手,而不是从 DirectoryFragment。因为 Activity 决定了整个应用的启动模式、Intent 分发、权限校验,是理解全局的钥匙。DocumentsActivity 继承自 BaseActivity,而 BaseActivity 里做了大量「根据 Intent 决定当前是 pick 模式还是 manage 模式」的判断,这是整个应用行为分叉的源头。
1.3 两种运行模式的本质区别
DocumentsUI 启动后只有两种身份,靠 Intent 的 action 区分:
- Pick 模式:三方应用调
ACTION_OPEN_DOCUMENT/ACTION_CREATE_DOCUMENT/ACTION_GET_CONTENT时进入。此时界面顶部有「取消/选择」按钮,用户选中后通过setResult把 URI 回传给调用方,并且可以申请持久化权限。 - Manage 模式:从设置里的「文件」入口、或者
ACTION_VIEW某个目录时进入。此时是完整的文件浏览体验,可以重命名、删除、新建文件夹、压缩等。
这两种模式共用同一套 Fragment 和 Adapter,差异通过 State 对象和 Menu 配置来控制。BaseActivity.getDisplayState() 返回的 State 里有个 action 字段,取值 ACTION_OPEN、ACTION_CREATE、ACTION_GET_CONTENT、ACTION_VIEW 等,后续所有 UI 分支几乎都围绕它展开。改造时如果你想加一个自定义入口,第一步就是确认它落在哪个 action 分支里,否则很容易出现「按钮显示了但点了没反应」的情况。
2. 核心组件是怎么串起来的
2.1 Activity 层的启动与 Intent 解析
DocumentsActivity 是整个应用的唯一主 Activity(DocumentsLauncherActivity 只是个别场景的别名)。它的 onCreate 里最关键的一步是 mState = getDisplayState(),这个方法在 BaseActivity 中实现,逻辑大致是:
- 读取 Intent 的 action、type、extra(如
EXTRA_INITIAL_URI、EXTRA_MIME_TYPES、EXTRA_ALLOW_MULTIPLE)。 - 结合
getCallingActivity()判断是内部调用还是外部调用。 - 构造一个
State对象,里面包含action、allowMultiple、allowCreate、stack(初始目录栈)等。
这里有个容易忽略的点:EXTRA_INITIAL_URI 的合法性校验。如果调用方传了一个当前 Provider 无法访问的 URI,DocumentsUI 不会崩溃,而是回退到默认根目录。这个回退逻辑在 State.build() 里,通过 DocumentsContract.isDocumentUri() 和 Root.getRootForUri() 双重判断。我在定制时遇到过调用方传了 content://com.thirdparty.provider/... 但该 Provider 没注册的情况,结果就是静默回退,排查了半天才发现是 Provider 侧的问题,不是 DocumentsUI 的锅。
2.2 Fragment 体系与 Loader 机制
界面主体是 DirectoryFragment,它负责渲染一个目录下的子项列表。它内部持有一个 DirectoryLoader(继承自 AsyncTaskLoader<DirectoryResult>),在 onCreateLoader 里创建,在 onLoadFinished 里拿到 Cursor 并交给 DirectoryAdapter。
为什么用 Loader 而不是 ViewModel + LiveData?这是历史包袱也是合理选择:Loader 天然绑定 LoaderManager,能在配置变更(旋转屏幕)时自动重连,且 ContentResolver 的 query 配合 Loader 的 onContentChanged 能实现数据变更自动刷新。Android 13 里虽然官方推荐 ViewModel,但 DocumentsUI 并没有迁移,因为迁移成本高且收益有限。你如果要做深度定制,不建议动 Loader 这套机制,牵一发动全身。
DirectoryResult 里除了 Cursor,还带了 exception、mIsSearchResult、mIsPartial 等状态。mIsPartial 表示当前目录只加载了一部分(比如 MTP 设备),UI 上会显示「正在加载更多」。这个字段在处理大目录时很有用,但很多二次开发者会忽略它,导致列表滚动到底部没有加载提示。
2.3 Provider 交互与 Roots 管理
侧边栏的「根目录」列表来自 RootsFragment + RootsLoader。RootsLoader 会遍历系统里所有注册了 DocumentsProvider 的包,调用每个 Provider 的 queryRoots(),把返回的 Root 聚合成侧边栏条目。
这里有个性能陷阱:Provider 数量多的时候,queryRoots() 是串行调用的。如果你在 ROM 里预装了很多带 Provider 的应用,冷启动时侧边栏会明显卡顿。我在一个项目里预装了 6 个带 Provider 的应用,冷启动侧边栏要 1.2 秒才出来。优化手段是给 RootsLoader 加并发查询,但要注意 Provider 的 queryRoots 可能不是线程安全的,需要加锁或限制并发数。实测并发数控制在 3 以内比较稳。
Root 对象里有个 mFlags 字段,常见取值有 FLAG_LOCAL_ONLY、FLAG_SUPPORTS_CREATE、FLAG_SUPPORTS_DELETE、FLAG_SUPPORTS_RECENTS 等。UI 会根据这些 flag 决定是否显示「新建文件夹」「删除」等菜单项。如果你自定义 Provider 时忘了设 flag,就会出现「菜单项灰掉」的问题,这是最高频的踩坑点之一。
3. 数据流与状态管理:一次点击到底发生了什么
3.1 从用户点击到 URI 回传的完整链路
假设用户在 Pick 模式下点了一个文件,完整链路是这样的:
DirectoryAdapter的onBindViewHolder里给 item 绑定了OnClickListener,点击后调用SelectionManager.toggleSelection()。SelectionManager更新选中集合,通知DirectoryFragment刷新 UI(底部「选择」按钮变为可用)。- 用户点「选择」,
PickerFragment或BaseActivity的onClick触发finishWithResult()。 finishWithResult()从SelectionManager取出选中的DocumentInfo,调用DocumentsContract.buildDocumentUri()构造最终 URI。- 如果是
ACTION_OPEN_DOCUMENT且需要持久化,调用ContentResolver.takePersistableUriPermission()。 setResult(RESULT_OK, intent)并finish()。
这条链路里第 5 步是重灾区。takePersistableUriPermission 要求 Provider 在 queryDocument 返回的 Cursor 里设置了 FLAG_SUPPORTS_PERSISTABLE_URI_PERMISSION,否则会抛 SecurityException。很多三方 Provider 没设这个 flag,导致调用方拿到的 URI 在进程重启后失效。排查时可以在 finishWithResult 里加日志打印 flag 值,一眼就能定位。
3.2 State 对象与配置变更
State 是 DocumentsUI 里一个被低估的类。它实现了 Parcelable,在 Activity 重建时通过 onSaveInstanceState 保存。它里面存了当前 action、当前目录栈、选中项、搜索状态等。理解 State 的序列化边界很重要:它只存 URI 和基本类型,不存 Cursor。所以旋转屏幕后,Fragment 会重新走一遍 Loader 加载流程,而不是复用旧数据。
这个设计带来的一个实际问题是:大目录旋转屏幕后会重新查询。如果目录里有几千个文件,旋转时会白屏一下。缓解办法是在 DirectoryFragment 里加一个「保留上次结果」的缓存,但要注意缓存失效问题。我一般不建议改,因为改动风险大于收益,除非你的场景对旋转体验有硬要求。
3.3 搜索与 Recents 的数据来源
搜索功能由 SearchFragment + SearchLoader 实现,它调用的是 Provider 的 querySearchDocuments() 接口。注意:不是所有 Provider 都支持搜索,只有设置了 FLAG_SUPPORTS_SEARCH 的 Root 才会出现在搜索结果里。如果你发现搜索不到某个目录,先查这个 flag。
Recents(最近文件)由 RecentsLoader 实现,它调用 Provider 的 queryRecentDocuments()。这个接口在 Android 13 里对 ExternalStorageProvider 的实现是基于 MediaStore 的,所以「最近文件」实际上反映的是媒体库的最近变更,而不是文件系统的最近访问。这个语义差异经常被误解,做需求时要跟产品讲清楚。
4. 改造实战:从编译到功能定制的完整路径
4.1 单独编译与调试环境搭建
在 AOSP 源码树里单独编译 DocumentsUI:
产物在 out/target/product/<device>/system/priv-app/DocumentsUI/DocumentsUI.apk。推送到设备:
调试时建议用 Android Studio 的「Attach to Process」,进程名是 com.android.documentsui。注意它是 priv-app,需要平台签名才能正常访问某些 Provider,用普通 debug 签名编译出来的 APK 推上去可能无法查询 ExternalStorageProvider,表现为列表空白。这是新手最容易卡住的地方——必须用平台签名,或者把 APK 放到 /system/app 并确保签名匹配。
4.2 常见定制需求与实现位置
| 需求 | 改动位置 | 注意事项 |
|---|---|---|
| 隐藏侧边栏某个 Root | RootsLoader 过滤 |
别直接改 Provider,影响面太大 |
| 默认打开某个目录 | State.build() 里改 stack |
要校验 URI 合法性 |
| 增加自定义菜单项 | DirectoryFragment.onCreateOptionsMenu |
注意 pick/manage 模式差异 |
| 修改文件排序 | DirectoryAdapter 的 Comparator |
要同步改 Model 层 |
| 禁用删除功能 | Root.mFlags 去掉 FLAG_SUPPORTS_DELETE |
改 Provider 侧更彻底 |
我重点说「默认打开某个目录」这个需求。很多人直接在 DocumentsActivity.onCreate 里 setIntent 改 URI,结果发现不生效。正确做法是在 State.build() 里,当 EXTRA_INITIAL_URI 为空时,注入你的默认 URI。但要注意:这个 URI 必须能被某个已注册的 Root 覆盖,否则会被回退逻辑吃掉。验证方法是打印 Root.getRootForUri() 的返回值,非 null 才算合法。
4.3 踩坑实录:Provider flag 缺失导致的菜单失效
有一次产品要求「在下载目录里支持新建文件夹」,我改了半天 UI 代码都没用,菜单项始终是灰的。排查链路是这样的:
- 先确认
DirectoryFragment的onPrepareOptionsMenu里判断条件是什么——发现是mState.canCreate()。 - 追
canCreate(),发现它读的是当前 Root 的FLAG_SUPPORTS_CREATE。 - 打印当前 Root 的 flags,发现
DownloadStorageProvider返回的 Root 没有这个 flag。 - 去
DownloadStorageProvider源码里看,发现它的queryRoots里确实没加FLAG_SUPPORTS_CREATE。 - 结论:不是 DocumentsUI 的问题,是 Provider 侧没声明能力。
这个坑的教训是:DocumentsUI 的 UI 能力完全由 Provider 的 flag 驱动,遇到「功能不显示」先查 flag,别急着改 UI。类似地,FLAG_SUPPORTS_RECENTS 决定是否出现在最近列表,FLAG_SUPPORTS_SEARCH 决定是否可搜索,FLAG_SUPPORTS_THUMBNAIL 决定是否显示缩略图。建议在调试时写个工具方法,把当前 Root 的所有 flag 打出来,能省大量时间。
4.4 踩坑实录:MTP 目录加载卡顿的优化
MTP 场景下,MtpDocumentsProvider 的 queryChildDocuments 是同步阻塞的,且一次只返回一批。DocumentsUI 的 DirectoryLoader 在 loadInBackground 里会循环调用直到拿完或达到上限。默认上限是 DirectoryLoader.LOADER_MAX_COUNT(我记得是 1000 左右)。如果 MTP 设备里文件很多,加载会非常慢。
优化思路有两个:一是调小单批数量、加快首屏渲染,让用户先看到一部分;二是给 DirectoryLoader 加超时,超时后显示「部分加载」。我实测把首批数量控制在 200 左右,首屏时间从 3 秒降到 800 毫秒。但要注意 mIsPartial 状态要正确设置,否则用户以为加载完了,实际还有数据没出来。
5. 架构层面的取舍与延伸思考
5.1 为什么它没有采用现代 Android 架构
DocumentsUI 的代码风格停留在 Loader + Fragment + 静态工具类的时代,没有 ViewModel、没有 Hilt、没有 Kotlin 协程。这不是团队懒,而是系统应用的稳定性优先级远高于架构先进性。它要跑在几亿台设备上,任何架构迁移都可能引入难以复现的崩溃。而且它大量依赖 ContentResolver 和 LoaderManager 的生命周期绑定,迁移到 ViewModel 需要重写数据层,收益不明显。
从业务架构视角看,这其实是一个「稳定优先、演进保守」的典型案例。跟物联网三层架构里平台层往往用最成熟而非最新的技术栈是一个道理——底层越稳,上层越敢创新。你做定制时如果非要引入协程,建议只在新增的独立功能里用,别动存量代码。
5.2 与三方文件管理器的边界
经常有人问:能不能基于 DocumentsUI 改一个完整的文件管理器?技术上可以,但要注意它的定位是「选择器」,很多文件管理器的能力它天生没有:比如批量重命名、文件压缩解压、FTP/SMB 挂载、root 权限访问。这些要么依赖 Provider 扩展,要么得自己加。我的建议是:如果只是要一个「能选文件」的界面,改 DocumentsUI 最省事;如果要做完整文件管理,另起一个应用更合适,否则你会在一堆 SAF 约束里挣扎。
5.3 后续可扩展的方向
如果你已经把 DocumentsUI 跑通并做了基础定制,可以往这几个方向延伸:一是自定义 DocumentsProvider,把自己的业务数据(比如云盘、数据库记录)暴露成文件树,这样不用改 DocumentsUI 就能接入;二是研究 DocumentsContract 的 Cursor 列定义,理解 COLUMN_DOCUMENT_ID、COLUMN_MIME_TYPE、COLUMN_FLAGS 这些字段怎么影响 UI;三是看 Root 的 COLUMN_ROOT_ID 和 COLUMN_AVAILABLE_BYTES,做存储空间展示。
我个人在实际操作中的体会是:DocumentsUI 的复杂度不在代码量,而在它和 Provider 之间的契约。你把 DocumentsContract 那套接口吃透,再看 DocumentsUI 的代码就会觉得顺理成章。反过来,如果只盯着 UI 层改,遇到问题会一直在表面打转。最后分享一个小技巧:调试 Provider 相关问题时,用 adb shell content query --uri content://com.android.externalstorage.documents/root 直接查 Provider 返回的数据,比在代码里打断点快得多。