Android SystemUI 架构、启动流程与二次开发避坑

简介围绕Android系统级UI框架整理的架构讲解演示文稿面向具备一定Android基础、希望深入系统源码的开发者与ROM定制人员用于梳理SystemUI的整体设计脉络与模块协作关系。内容从SystemUI的定义和源码位置切入逐一说明状态栏、通知、锁屏、最近任务、音量与电量UI、铃声播放、画中画、生物识别解锁等子模块的职责边界并给出结构图、类图与启动流程三类架构图示后半部分拆解通知的存放位置、注册流程、从系统发送到SystemUI的链路以及框架内的处理流程同时覆盖导航栏、快捷设置等常见界面。压缩包内为1个pptx文件约11.64MB以图文页组织便于按章节顺序阅读或直接用于团队内部分享。目前已有403人学习。1. SystemUI 不是普通 App一个 apk 撑起整机系统级交互面客户要删掉状态栏上一个多余图标我在设置里翻了半小时没找到开关最后发现它压根不在设置里而是 SystemUI 的一个 StatusBarIconView。这类事在系统层做软件开发的头两年我碰到过不止一次。SystemUI 架构设计最容易误导新人的点在于它明明打成 apk、源码也躺在 packages 目录下看着和普通应用没差但签名、权限、启动方式、窗口层级全在应用之上。你手里这台机器的状态栏、锁屏、导航栏、快捷设置、最近任务、通知展示全塞在这一个模块里。适合已经拿到系统源码、要做定制开发的人只想换个主题色的也能看只是改动的落点很可能和你想的不一样。2. 模块划分从组件表看九个功能块怎么被按需拉起SystemUI 的「包罗万象」不是一句形容词它是实打实塞在一个 apk 里的九个左右功能模块。拆这份资源时最有价值的不是那几张架构图而是模块之间几乎不互相依赖、按需启动这个设计——你砍掉一块其他块照样能起来当然有例外下面会讲。搞清这一点后面定位代码就不会满仓库乱 grep。2.1 一张字符串数组决定哪些模块开机启动模块的启停开关集中在一个资源数组里路径在 SystemUI 模块自己的 res/values 下名字叫config_systemUIServiceComponents。里面每一项就是一个类的全限定名!-- frameworks/base/packages/SystemUI/res/values/config.xml -- string-array nameconfig_systemUIServiceComponents translatablefalse itemcom.android.systemui.keyguard.KeyguardViewMediator/item itemcom.android.systemui.recents.Recents/item itemcom.android.systemui.volume.VolumeUI/item itemcom.android.systemui.statusbar.phone.PhoneStatusBar/item itemcom.android.systemui.pip.PipUI/item itemcom.android.systemui.power.PowerUI/item itemcom.android.systemui.media.RingtonePlayer/item itemcom.android.systemui.statusbar.phone.BiometricDialogImpl/item /string-array这份梳理稿成稿时间偏早PhoneStatusBar这个叫法在新分支里已经被拆成了CentralSurfaces加一票 Fragment/Controller 的组合但「数组驱动启动」这个机制一直没变。所以看架构图时可以只记结构真正动手改落点一定要以你手上分支的实际类名为准。数组的消费方是SystemUIApplication。它继承Application本身不干活只做一个容器把每个类反射实例化、注入 Context、再调start()。主干大概长这样// SystemUIApplication.java简化保留主干逻辑 public class SystemUIApplication extends Application { private final ArrayMapClass?, Object mServices new ArrayMap(); private boolean mServicesStarted; Override public void onCreate() { super.onCreate(); setTheme(R.style.Theme_SystemUI); // 只做容器级初始化 } public void startServicesIfNeeded() { if (mServicesStarted) return; // 幂等重复调用不重复起 String[] names getResources() .getStringArray(R.array.config_systemUIServiceComponents); startServicesIfNeeded(names); mServicesStarted true; } private void startServicesIfNeeded(String[] services) { for (String clsName : services) { Class? cls Class.forName(clsName); // 反射拿类 SystemUI obj (SystemUI) cls.newInstance(); // 必须 public 无参构造 obj.mContext this; // 基类注入 Context mServices.put(cls, obj); obj.start(); // 各模块自己决定做什么 } } }关键参数就三个clsName必须能被Class.forName找到否则开机直接抛ClassNotFoundExceptionSystemUI 起不来newInstance()要求目标类有 public 无参构造这是很多新手自定义模块时第一个翻车的地方obj.start()里通常做三件事——WindowManager.addView()、注册各种 Listener、或者bindService连别的系统服务。改模块最轻的方式就是动这张表加一行多一个模块删一行少一个。看起来很美但顺序是有讲究的。KeyguardViewMediator通常排在很前面因为状态栏、通知面板在初始化时会去问KeyguardUpdateMonitor拿锁屏状态。你要真把锁屏那行注释掉十有八九在CentralSurfaces初始化阶段就 NPE日志里一串Attempt to invoke virtual method on a null object reference。稳妥做法是删模块时把它相关的依赖点一起改别指望「按需启动」等于「随便删」。2.2 状态栏、锁屏、最近任务三条主线各自的入口九个模块里日常改动八成集中在前三个。搞清它们的入口类定位效率会差一个量级。状态栏这条线负责图标区、通知折叠区、快捷设置的挂载点。老分支里是PhoneStatusBar它自己做 WindowManager 的 addView自己管一堆 view新分支把它拆成CentralSurfaces管生命周期和窗口加CollapsedStatusBarFragment管图标布局。你遇到「状态栏图标位置偏了」这类问题先去CollapsedStatusBarFragment的布局文件里找别一头扎进 Java 代码。锁屏这条线的核心是KeyguardViewMediator名字里虽然写着 View但它本质上是个状态机doKeyguardLocked()决定要不要上锁onSystemReady()响应开机完成verifyUnlock()处理解锁校验。它旁边站着KeyguardUpdateMonitor负责订阅 SIM 卡状态、指纹/人脸回调、息屏广播再把变化抛给 mediator。改锁屏行为先确认自己改的是「状态迁移」还是「界面展示」前者动 mediator后者动 Keyguard 相关的 Fragment两边的调试方式完全不同。最近任务这条线是最容易被误伤的一条。早期Recents是 SystemUI 里的一个模块自己做任务列表后来转场和任务数据被拆给了桌面侧的 quickstepSystemUI 这侧只留OverviewProxyService做代理负责把 Recents 键的触摸事件和手势转给桌面进程。所以你在 SystemUI 里翻遍代码也找不到「任务卡片怎么画」那段不是你找错了是它压根不在这儿了。2.3 剩下六块音量、电量、铃声、画中画、生物识别、通知渠道这几块改动频率低但出问题时排查成本很高因为很多人不知道它们存在。模块入口类主要职责典型改动点VolumeUIvolume.VolumeUI音量条、音量面板音量条样式、超时消失时间PowerUIpower.PowerUI低电量提醒、无线充电提示低电量阈值、提示文案RingtonePlayermedia.RingtonePlayer铃声、闹钟播放铃声焦点抢占逻辑PipUIpip.PipUI画中画窗口管理分屏/画中画切换策略BiometricDialogImplstatusbar.phone.BiometricDialogImpl指纹/人脸/虹膜解锁弹层解锁动画、提示文案通知渠道由通知链路内建通知分组、排序、悬浮分组规则、悬浮阈值VolumeUI和PowerUI是典型的「出问题才知道存在」客户反馈「插上充电器没提示」你翻半天通知代码结果是PowerUI里注册的广播被别的模块拦截了。RingtonePlayer更隐蔽它经常在独立进程里跑因为铃声播放要抢音频焦点和 UI 主进程放一起容易互相拖死。BiometricDialogImpl则是解锁体验定制绕不开的一块改解锁动画基本都要从这里下手。提示删模块前先 grep 一下依赖。BiometricDialogImpl被KeyguardViewMediator、CentralSurfaces多处引用单独注释掉启动项大概率编译过了但运行崩。3. 架构与启动流程SystemUIService 到 SystemUIApplication 的两跳架构图那几页很多人扫一眼就过去了觉得「不就一堆框框」。实际上 SystemUI 的架构难点不在类图多复杂而在于它横跨了三个层次系统服务层谁把它拉起来、应用进程层模块容器怎么组织、窗口服务层凭什么能盖在所有应用上面。这三层搞混了调 bug 就会一直在错误的层里打转。3.1 结构图里真正该看的三条线第一层是进程与容器的边界。SystemUI 本身是一个普通应用进程包名com.android.systemui跑在 system_server 之外的独立进程里。它和系统其他部分的所有交互都走 Binder往下问NotificationManagerService要通知往上通过WindowManagerService加窗口。所以你在 SystemUI 里写代码任何跨进程调用都要考虑线程切换这是后面通知链路那一章反复强调主线程 post 的原因。第二层是模块容器。上一章讲的SystemUIApplication就是这个容器它把所有模块的实例塞进一个ArrayMap需要的时候按 class 取。这个设计的好处是模块间通过取容器实例通信耦合度低坏处是容器里取不到的时候没有任何编译期提示只能靠运行时 NPE 告诉你依赖错了。第三层是窗口类型与层级。SystemUI 的每个可视模块最终都要调WindowManager.addView而窗口类型决定了它盖在谁上面。状态栏、导航栏用的是系统级窗口类型普通应用窗口永远盖不住它们。这也是为什么改主题、改背景色这类需求你改应用里的布局没用——它根本没和应用在同一个 z 序里。3.2 两跳启动SystemServer 拉起 ServiceService 再唤醒 Application开机阶段system_server 在startOtherServices里会把 SystemUI 拉起来这一跳是显式指定组件名的// SystemServer.java简化开机时通过组件名直接启动 private void startSystemUi(Context context, WindowManagerService wm) { Intent intent new Intent(); intent.setComponent(new ComponentName( com.android.systemui, // 包名 com.android.systemui.SystemUIService)); // 服务类全名 intent.addFlags(Intent.FLAG_DEBUG_LOG_RESOLUTION); context.startServiceAsUser(intent, UserHandle.SYSTEM); // 以 system 用户启动 }参数里startServiceAsUser的第二参指定了用户这意味着 SystemUI 是跟着用户走的多用户场景下每个用户会有一份实例实际实现里主用户之外的行为更复杂但定位问题时知道「用户」这个维度很重要。FLAG_DEBUG_LOG_RESOLUTION是个调试标记加上之后启动过程会在日志里多打一些解析信息排查启动失败时很有用。Service 自己几乎什么都不做只负责接力public class SystemUIService extends Service { Override public void onCreate() { super.onCreate(); // 走到这里 Application 已经创建可以安全地开始拉模块 ((SystemUIApplication) getApplication()).startServicesIfNeeded(); } Override public IBinder onBind(Intent intent) { return null; // 不对外提供绑定纯启动器 } }为什么非要绕这一跳不直接在Application.onCreate里起模块因为Application.onCreate触发时机不确定可能被别的入口提前拉起那时窗口服务未必就绪。用 Service 做接力点等于用系统对「服务启动」的时序保证换取一个确定性的初始化窗口。这个设计思路在后来的Startable抽象里被保留了下来只是实现从 Service 变成了dagger注入的Startable集合。3.3 窗口为什么能盖住一切类型和权限是两个门槛加窗口那段代码参数配置是绕不开的// 以状态栏窗口为例简化 WindowManager.LayoutParams lp new WindowManager.LayoutParams( MATCH_PARENT, WRAP_CONTENT, WindowManager.LayoutParams.TYPE_STATUS_BAR, // 系统窗口类型 WindowManager.LayoutParams.FLAG_NOT_FOCUSABLE | WindowManager.LayoutParams.FLAG_TOUCHABLE_WHEN_WAKING, PixelFormat.TRANSLUCENT); lp.gravity Gravity.TOP; lp.setTitle(StatusBar); mWindowManager.addView(mStatusBarWindow, lp);三个参数值得逐个说。TYPE_STATUS_BAR决定层级换成应用层类型立刻就会被应用窗口盖住FLAG_NOT_FOCUSABLE让状态栏不抢焦点否则所有输入法都弹不出来FLAG_TOUCHABLE_WHEN_WAKING是给唤醒那一下用的保证息屏时也能响应触摸。但真正卡人的不是这些 flag是权限。加系统级窗口需要INTERNAL_SYSTEM_WINDOW这个权限的保护级别是 signature|privileged普通应用申请不到甚至在 Android 9 之后还要额外的INTERNAL_SYSTEM_WINDOW白名单。这就引出下一章的坑你本地编译出来的 apk 如果不带平台签名装上去启动那一刻就被拒日志里是SecurityException而不是你以为的「代码没生效」。4. 通知链路从 notify() 到状态栏那一行字的完整路径通知是 SystemUI 里唯一一条横跨「应用 → 系统服务 → SystemUI → 窗口」四段的完整链路也是面试和实际排查里出现频率最高的。把这条链路走通一遍基本就理解了 SystemUI 和系统服务之间是怎么协作的。4.1 注册与绑定Listener 怎么被通知服务认识SystemUI 里的通知监听器继承自NotificationListenerService这个基类在框架层负责和服务端建立双向 Binder。应用进程启动时NotificationListenerService会向NotificationManagerService注册自己服务端维护一份 listener 列表每个 listener 对应一个INotificationListener的 Binder 代理。注册这一步有个容易被忽略的细节listener 需要用户授权通知使用权SystemUI 自己因为是系统应用、在默认白名单里开机就自动获得授权。你自己写一个第三方应用去监听通知就必须引导用户去设置页手动打开开关否则onNotificationPosted永远不回调。这个差异是很多人在移植 SystemUI 代码到自己 App 里时踩的第一个坑。组件表里NotificationChannels那一项负责的就是 SystemUI 侧的渠道管理它在启动时会把系统渠道的配置读进来用于后续的通知过滤和分组。渠道这个概念对开发者不陌生但在 SystemUI 侧它的角色是「读」而不是「写」——应用侧写渠道SystemUI 侧按渠道重要性决定这条通知要不要展示、展示成什么样。4.2 跨进程回调onNotificationPosted 进来之后发生了什么应用调notify()请求先到系统服务服务排完序之后通过 Binder 回调到 SystemUI 的 listener。回调进来的是StatusBarNotification和一个RankingMap快照// NotificationListener.java简化 Override public void onNotificationPosted(final StatusBarNotification sbn, final RankingMap rankingMap) { // 这里是 Binder 线程绝对不能直接碰 View if (sbn null) return; if (onPluginNotificationPosted(sbn, rankingMap)) return; // 插件先截胡 mMainHandler.post(() - mEntryManager.onNotificationPosted(sbn, rankingMap)); // 切回主线程 }两个参数的含义要分清sbn是这条通知的完整快照包含包名、id、tag、时间和 contentViewrankingMap是当前所有通知的排序快照用来判断这条通知的相对位置。快照这个特性意味着你不能把它存起来等会儿再用排序一变旧快照就过期了该重新取的时候要重新取。onPluginNotificationPosted是扩展点插件可以在这里把某条通知拦下来或者改写拦下来之后主流程就不再走。这个机制在定制场景里很有用比如你想屏蔽某个包的所有通知改这里比改应用侧省事。主线程 handler post 过去之后进入真正的内容管理阶段// NotificationEntryManager简化 public void onNotificationPosted(StatusBarNotification sbn, RankingMap rankingMap) { if (!mNotifCollection.isNotificationKnown(sbn.getKey())) { // 新通知才需要跑过滤更新走另一条路径 if (shouldFilterOut(sbn)) return; // 前台服务、低优先级、渠道被关 } mNotifCollection.onNotificationPosted(sbn, rankingMap); // 落库 mGroupCoordinator.onNotificationPosted(sbn); // 分组 mHeadsUpManager.onNotificationPosted(sbn); // 悬浮判定 }getKey()是包名加 id 加 tag 拼出来的唯一键也是「同一条通知更新」和「来了一条新通知」的判断依据。shouldFilterOut里那三条过滤规则是绝大多数「通知怎么不显示」的根因所在后面避坑那一章会展开。4.3 分组、排序与悬浮三条并行的处理线mGroupCoordinator负责把同一个应用的多条通知收进一个组。它的输入是通知自带的 group key输出是一个逻辑分组UI 层按组渲染成一张卡片或者一叠卡片。组的行为受应用侧setGroup()和setGroupSummary()控制SystemUI 侧只能决定怎么展示不能凭空创造分组。mHeadsUpManager负责悬浮通知也就是顶部弹出来的那条横幅。它的判定依据是通知的重要性、当前是否全屏、以及一个全局的节流窗口——短时间内来太多条后面的会被压掉。这个节流窗口是硬编码的改它得动HeadsUpManager里的常量属于改行为不改接口的那类操作。排序则发生在更早的路径上由系统服务的NotificationRankingManager完成SystemUI 拿到的rankingMap已经是排好序的结果。所以你要改「哪条通知排前面」方向不是在 SystemUI 里改 adapter 的 comparator而是去改系统服务侧的排序权重。这个方向判断错了会浪费一整天。5. 排查与避坑编译、推送、调试里最容易翻车的五处前面四章讲的是「应该怎么理解」这一章讲「实际会怎么崩」。SystemUI 的调试体验在系统模块里算偏差的它没有独立入口崩了整机没状态栏日志还被开机流程刷掉一半。下面这些坑我基本都亲自踩过。5.1 先确认进程活着三条命令定位当前状态出问题别急着看代码先确认 SystemUI 进程现在是什么状态。三条命令按顺序来adb shell ps -A | grep systemui看进程在不在adb shell dumpsys activity processes | grep -i systemui看有没有被系统反复重启adb logcat -b all -d | grep -i systemui\|AndroidRuntime看有没有 FATAL。如果进程不在、重启次数还一直涨那就是启动阶段就崩了跟你的功能改动无关先解决启动问题。5.2 五条踩坑记录现象、原因、解决第一条push 完 apk 黑屏状态栏消失。现象adb push覆盖/system/priv-app/SystemUI/下的 apk重启 SystemUI 之后状态栏没了日志刷SecurityException或FATAL EXCEPTION。原因本地编译产物是 debug 签名和系统里的平台签名对不上系统直接拒绝加载这个包另外如果目录里有旧的 oat/vdex还可能因为校验失败连带崩掉。解决在源码树里用m SystemUI出包它带的是平台签名推之前先清oat目录或者干脆整包刷system.img。别在量产机上直接 push我见过一次把机器推到开不了机最后只能线刷救回来。第二条改了最近任务的代码界面毫无变化。现象在 SystemUI 里改了 recents 相关逻辑编译通过长按方块键出来的还是老样子。原因新版最近任务列表由桌面侧的 quickstep 接管SystemUI 只剩OverviewProxyService做转场代理和手势转发真正画卡片的那段代码根本不在这个模块里。解决先确认你所在分支的 recents 归属看OverviewProxyService往哪个组件发请求要改卡片布局就得去桌面侧仓库SystemUI 里只能改转场动画和触摸事件的拦截时机。第三条通知不显示或者显示两条。现象应用发了通知状态栏要么没有要么两条一模一样的。原因不显示通常是渠道被降级成IMPORTANCE_NONE或者通知被判定为前台服务、低优先级而被过滤显示两条通常是notify()时 tag 和 id 组合不一致被系统当成两条不同通知。解决先查渠道重要性getNotificationChannel(id).getImportance()打印出来看再确认同一类通知用固定的notify(tag, id, n)别一会儿带 tag 一会儿不带。还有一种隐藏原因是自己在 listener 里手动往状态栏塞了图标和系统自动渲染的撞了把那段手动逻辑删掉即可。第四条状态栏图标改了不刷新。现象换了个电量图标插拔充电器之后图标不跟着变。原因图标刷新走的是图标控制器的统一入口addIcon/setIcon刷新时会做过渡动画和去重如果自己持有了StatusBarIconView直接setImageDrawable就绕过了这条通道后续 controller 的更新覆盖不回来。解决所有图标统一走 controller别在业务代码里直接操作 view。这个规矩听起来简单但定制项目赶工时最容易破破一次后面全是玄学问题。第五条logcat 里抓不到任何相关日志。现象加了日志adb logcat -s SystemUI一片空白。原因进程其实已经崩了在重启循环日志被反复的启动日志刷掉或者 log buffer 太小被别的模块冲掉还有一种是 tag 被改过你按老 tag 过滤当然没有。解决先adb logcat -b all不过滤全量抓抓完再搜同时确认进程存活。buffer 不够就临时加大adb logcat -G 16M。这招是血泪经验换来的早年间我在一个刷机包里找了半天「日志没打」最后发现是进程压根没起来。6. 二次开发改一个图标到加一块自有面板的落点选择改动前先做一道选择题这个改动属于「换个皮」「加个入口」还是「加个模块」三种落点完全不同选错方向就是白干。改动目标落点影响面换图标、改颜色、调间距对应 Fragment 的布局和 drawable小可随时回滚状态栏加一个自定义图标图标控制器的注册处中注意刷新通道快捷设置加一个磁贴QSTileImpl子类 Host 注册中要注意权限加一整块自有 UI组件表新增一项 SystemUI子类大注意启动顺序最轻的改动是换皮直接动布局和资源不碰 Java。加图标要谨慎一点必须走 controller这点在避坑里说过。加模块最重但也是最体现这套架构价值的地方你只要写一个SystemUI的子类在组件表里加一行它就跟着开机流程起来了。快捷设置磁贴是我改得最多的一类因为成本低、见效快。骨架大概是这样// 自定义磁贴简化 public class DevTile extends QSTileImplBooleanState { public DevTile(QSHost host) { super(host); } Override protected void handleClick() { // 点击后切换状态真实项目里一般在这里发广播或改系统设置 refreshState(); } Override protected void handleUpdateState(BooleanState state, Object arg) { state.value true; // 当前开关状态 state.label 调试开关; // 磁贴标题 state.icon ResourceIcon.get(R.drawable.ic_settings); // 磁贴图标 } Override public BooleanState newTileState() { return new BooleanState(); } }三个重写方法各管一件事handleClick处理点击handleUpdateState决定长什么样newTileState提供状态容器。写完还要在 Host 的磁贴工厂里注册否则它不会出现在快捷设置面板里。这里有个小技巧注册时给的 spec 字符串要全局唯一重名会导致后注册的覆盖前面的而且不报错只是磁贴静默消失。验证方式我习惯分三步走先在模拟器或者工程机上验证功能再在真机上验证权限相关的分支很多问题只有平台签名环境才暴露最后跑一遍开机冷启动确认模块启动顺序没被自己打乱。第三步最容易被跳过但恰恰是问题最多的一步。从那以后我每次动组件表或者新增窗口都强制走一遍完整的冷启动加日志全量抓取宁可多花二十分钟也不想再经历一次「改了五行代码机器开不了机」。希望帮到你。本文还有配套的精品资源点击获取