BottomSheetDialogFragment底部导航栏颜色调整全攻略

做 Android 开发这几年，大家应该都躲不开BottomSheetDialogFragment这个弹窗利器，尤其做地图、电商、IM 聊天这类 App 的时候，底部弹出的分享面板、评价面板、筛选面板几乎全靠它。但不少朋友一开始都会遇到同一个坑：弹窗弹出来本身没问题，可系统底部导航栏的颜色经常失控——要么弹窗背景是白的，导航栏却黑底白字，突兀得离谱；要么明明改成浅色导航栏了，底部的返回键、手势条却和弹窗内容叠在一起看不清。这个“BottomSheetDialogFragment底部导航栏颜色调整”的需求，看似只是调个颜色，实际上牵扯到 Dialog 的 Window 层级、系统 UI 模式、不同安卓版本的兼容规则，稍不注意就会出现“在模拟器上正常、到真机上翻车”的尴尬局面。

这篇文章我不想罗列零散的 API，而是按“现象 → 原因 → 配置 → 实操 → 避坑”的顺序，从原理到一份可以直接抄的代码讲完整。适合刚接触BottomSheetDialogFragment、对窗口系统栏控制还不够熟的开发者，也适合那些想系统性搞懂“为什么改了不生效”“为什么 Android 15 上又变了一个写法”的人。

1. 先搞清楚 BottomSheetDialogFragment 的“底部导航栏颜色”到底是什么

1.1 弹窗的窗口层级与系统导航栏的关系

先明确一个概念：你的 BottomSheet 内容视图的背景，并不等于弹窗所在 Window 的背景。

BottomSheetDialogFragment内部维护了一个BottomSheetDialog。这个 Dialog 本身是一个独立的 Window 对象，它的尺寸、背景、系统栏属性都受这个 Window 控制。换句话说，当你讲“底部导航栏颜色”时，你操作的实际目标是dialog.getWindow()，而不是fragment的布局根节点。

很多人第一次改颜色时，直接去 BottomSheet 的内容布局上加一个白色背景，觉得“我的弹窗已经白了，导航栏应该也跟着白吧”。实际上这个白色只是覆盖了屏幕中间弹窗可视区域，底部虚拟导航栏那一小块区域通常由 Window 的navigationBarColor决定，默认可能是黑的、也可能带半透明遮罩，于是你看到一条和弹窗颜色完全脱节的色带。想让它跟随弹窗而变，本质是在改 Window 的系统栏属性。

// 你以为是改它 view.rootView.setBackgroundColor(Color.WHITE) // 真正要改的是它 dialog?.window?.navigationBarColor = Color.WHITE

1.2 三键导航和手势导航的差异

把颜色控制做对之前，先明白目标设备上的“底部导航栏”到底长什么样。

在带虚拟三键导航的设备上，底部是一个有明确背景色的条形区域，系统用 Window 的navigationBarColor来填充它。此时调整颜色是直观的，改背景色、改前景图标颜色即可。

在手势导航设备上，绝大多数情况下底部没有一块矩形色块，只保留一条细细的手势指示条。但系统为了兼容旧应用，会在界面底部叠加一层半透明遮罩或对比度层。很多国产 ROM 的高版本也一样，窗口背景是浅色的时候，你依然能看到底部那条手势条，而它本身的颜色取决于 Window 的背景和系统栏标志共同作用。

关键点总结一下：

所以做得好的“颜色调整”，从来不是只给navigationBarColor赋个值就完事，还得配合设置“导航栏上的图标是深色还是浅色”。否则你背景改成浅色了，手势条可能还是亮的，根本看不清。

1.3 颜色与图标对比度双开关

Android 系统提供了一种面向深色/浅色背景的主题化配置方式：给系统栏背景设置颜色后，还需要告诉系统“现在底部的图标适合用深色还是浅色”。

在传统的 View API 里，这个开关叫SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR。在 AndroidX 的兼容 API 里，它变成了：

val controller = WindowInsetsControllerCompat(window, window.decorView) controller.isAppearanceLightNavigationBars = true

isAppearanceLightNavigationBars = true的含义是“允许把导航栏上的图标表现为暗色”。浅色背景配合它，图标才会自动变深色；反过来说，深色背景需要把它设为false，图标保持白色。颜色调整一旦只调背景不调这个 flag，问题差不多就来了。

2. 先梳理你的需求：是延续背景色、跟随主界面，还是动态切换

2.1 不同交互场景的导航栏表现

我不能直接告诉你一套固定代码，因为不同 App 对弹窗底部导航栏的需求并不一致。

有的场景希望弹窗的白色背景一直延续到屏幕最底部，让整个底部看起来像一张完整的卡片，这时候导航栏颜色要跟随弹窗内容区的背景色。有的场景则希望弹窗弹出时导航栏保持主界面原本的颜色，不要突然跳成弹窗的白色。还有不少 App 的分享面板是全屏 BottomSheet，一弹出就覆盖整个屏幕，这种时候导航栏颜色通常要跟随 BottomSheet 的页面背景；如果只是半屏弹窗，弹窗之外还有一层黑色蒙层，导航栏放在透明区域里会显得更自然。

列举一下最常见的三种需求：

• 半屏弹窗，白色内容区，导航栏保持主界面默认色或半透明。
• 半屏弹窗，白色内容区，希望白色把导航栏也盖住，看起来中间没有割裂。
• 全屏风格的 BottomSheet，页面本身就是浅色/深色的大块头，导航栏颜色必须和页面背景严格一致。

你会发现不同需求对导航栏颜色的处理方式是不同的。尤其是第二种和第三种，如果弹窗高度够不到底部系统栏区域，强行把导航栏设置成弹窗背景色反而会造成很怪异的“整块白色中夹着一条蒙层”。这也是为什么很多咨询群里的问题没有一个标准答案，要看产品定义。

2.2 图标颜色怎么搭配才不翻车

导航栏颜色也不是随便找个色值替换就收工。如果底栏背景被设置成浅色，那么导航栏上的“返回箭头”“桌面方块”“手势条”这些图标会变成深色才看得到；反过来如果背景是深色，就必须保持浅色图标。

这个原则几乎可以做成一张速查表：

这里踩坑概率很大。比如底栏背景原来是深色的，你给导航栏设成白色，没同步设置isAppearanceLightNavigationBars，那么整条导航栏会变成“白底白字”，图标肉眼几乎看不见。这也是标题里“颜色调整”总是被连带问到的原因——调整目标不是单纯地“变颜色”，而是让整条系统栏的颜色与图标状态保持合理对比度。

3. 常规改法为什么经常改不好：三个隐含前提

3.1 在错误的生命周期阶段设置

BottomSheetDialogFragment的窗口不是随时都能拿到的。你在onCreateView里写dialog?.window，经常会拿不到有效对象；即便拿得到，此时 Window 还没有真正 attach 到系统，很多属性设置完会被后续的初始化流程覆盖掉。

最稳妥的入口是onStart()。这个阶段 Dialog 已经进入可见状态，Window 对象已经完整创建，此时再改navigationBarColor、设置 Insets 相关属性，基本都能生效。我看到过很多“为什么动态设置了没反应”的例子，大部分是把设置代码放在了onCreateView或者构造函数里，时机错了，自然白干。

override fun onStart() { super.onStart() dialog?.window?.navigationBarColor = ContextCompat.getColor(requireContext(), R.color.sheet_bg) }

3.2 没有在主题里预留窗口背景

BottomSheetDialog默认使用的 Dialog 主题里，窗口背景和普通 Activity 不同。如果你不在主题层面处理好windowBackground、windowIsTranslucent这些属性，后续这些背景会叠在内容区和系统栏之间，导致你设了导航栏颜色却依然有一条灰灰的色带。

尤其当你的弹窗内容上方有圆角背景，或者带着阴影遮罩时，窗口本身如果是不透明的，最底层那一条系统栏区域会被窗口背景盖掉一部分，视觉上就会“明明设置了颜色，但底部那条颜色不对”。

很多成熟项目的做法是派生一个专用主题，保证 Dialog 窗口背景透明，让真正的内容区去控制可见视觉：

<style name="Theme.App.BottomSheetDialog" parent="Theme.MaterialComponents.Light.BottomSheetDialog"> <item name="android:windowBackground">@android:color/transparent</item> <item name="android:windowIsTranslucent">true</item> </style>

然后在BottomSheetDialogFragment里重写getTheme()返回它。

3.3 没区分 Activity 窗口和 Dialog 窗口

你如果搜到很多答案是“在 Activity 的 onCreate 里设置导航栏颜色”，那是只适用于普通页面。对于弹窗窗口，它附着在另一个 Window 上，需要重新为这个 Dialog Window 设置，不能指望 Activity 上的设置能覆盖 Dialog。这也是为什么有人觉得“明明设置过全局底部导航栏了，弹窗一出来还是黑底白字”。

所以代码里必须显式拿到 Dialog 的 Window：

override fun onCreateDialog(savedInstanceState: Bundle?): Dialog { val dialog = super.onCreateDialog(savedInstanceState) as BottomSheetDialog return dialog }

拿不到时就要一步步排查是 Window 为空，还是设置被后续覆盖。

4. 完整实操：一份可以照抄的底部导航栏颜色调整方案

4.1 第一步：准备专用主题和颜色资源

先在colors.xml里定义一份带语义的色板，别硬编码十六进制。这样在“亮色模式”和“暗色模式”下分别切换颜色时更方便。

<color name="sheet_bg_light">#F7F8FA</color> <color name="sheet_bg_dark">#212121</color>

然后定义一个 BottomSheet 专用主题，放在styles.xml：

<style name="Theme.App.BottomSheetDialog.Base" parent="Theme.MaterialComponents.Light.BottomSheetDialog"> <item name="android:windowBackground">@android:color/transparent</item> <item name="android:windowIsTranslucent">true</item> <item name="android:navigationBarColor">@color/sheet_bg_light</item> <item name="android:windowLightNavigationBar">true</item> </style>

如果你的最低 API 在 21 以下，需要在values-v21里额外补充样式；如果最低版本就是 21 或以上，直接写就好。关键是第一，窗口背景保持透明；第二，主题里先兜底设置一次导航栏颜色，避免 Fragment 代码还没来得及执行时出现一瞬间的黑底。

4.2 第二步：在 Fragment 里设置 Window 属性

下面这份代码是许多项目里的通用写法。它做四件事：

• 清除半透明导航栏的 Flag，避免旧系统叠加遮罩。
• 设置一个确定的navigationBarColor。
• 通过 Insets 控制器设置前景图标明暗。
• 在弹出之前做好兜底。

class ColorSheetDialogFragment : BottomSheetDialogFragment() { override fun getTheme(): Int = R.style.Theme_App_BottomSheetDialog_Base override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? ): View? { return inflater.inflate(R.layout.fragment_color_sheet, container, false) } override fun onStart() { super.onStart() applyNavigationBarColor() } private fun applyNavigationBarColor() { val window = dialog?.window ?: return val context = requireContext() // 目标颜色：这里假设弹窗背景是亮色，导航栏跟随弹窗背景 val targetColor = ContextCompat.getColor(context, R.color.sheet_bg_light) // 旧写法需要这两个 Flag 配合，才能直接设置纯色背景 window.addFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS) window.clearFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION) window.navigationBarColor = targetColor // API 30 以上更推荐走 InsetsController val controller = WindowInsetsControllerCompat(window, window.decorView) controller.isAppearanceLightNavigationBars = true } }

这里要说明FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS的作用：它表示允许 Window 自己绘制系统栏背景，这样navigationBarColor才会生效。FLAG_TRANSLUCENT_NAVIGATION如果不清除，导航栏区域会被强制加上半透明黑色遮罩，设置纯色会显得脏。

4.3 第三步：动态切换导航栏颜色

如果弹窗内容分为多页、每页背景深浅不一样，你需要根据页面状态动态改变导航栏颜色。比如一个列表页是白底，点进详情页变成黑底，那底部导航栏颜色要做联动。

写一个可复用的工具方法：

object SheetSystemBarHelper { fun applyNavigationBar( window: Window, @ColorInt bgColor: Int, lightIcons: Boolean ) { window.addFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS) window.clearFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION) if (window.navigationBarColor != bgColor) { window.navigationBarColor = bgColor } val controller = WindowInsetsControllerCompat(window, window.decorView) controller.isAppearanceLightNavigationBars = lightIcons } }

调用时，你要从 Fragment 的dialog?.window传入。一个容易被忽略的小细节：先判断颜色是否真的变化了再赋值，可以避免无谓的绘制开销，也防止系统栏闪烁。

4.4 第四步：伴随 BottomSheet 展开/收起状态做侧滑联动

有些产品期望当 BottomSheet 完全展开时页面内容把导航栏“吃掉”，而 BottomSheet 收起后露出背后主界面的导航栏颜色。我们可以用BottomSheetBehavior.BottomSheetCallback监听状态。

在 BottomSheet 布局的根节点挂一个回调：

private fun attachSheetCallback() { val bottomSheet = dialog?.findViewById<View>( com.google.android.material.R.id.design_bottom_sheet ) ?: return val behavior = (bottomSheet.layoutParams as? CoordinatorLayout.LayoutParams) ?.behavior as? BottomSheetBehavior<*> ?: return behavior.addBottomSheetCallback(object : BottomSheetBehavior.BottomSheetCallback() { override fun onStateChanged(bottomSheet: View, newState: Int) { if (newState == BottomSheetBehavior.STATE_EXPANDED) { dialog?.window?.let { SheetSystemBarHelper.applyNavigationBar( it, ContextCompat.getColor(requireContext(), R.color.sheet_bg_light), true ) } } } override fun onSlide(bottomSheet: View, slideOffset: Float) { // 如果有动态渐变需求，可以在这里根据 slideOffset 插值颜色 } }) }

slideOffset在展开时为 0，收起后转为负值，拖动过程中可能连续变化。如果产品想要“弹窗向上滑时导航栏颜色跟着渐变”，可以在这里写颜色插值逻辑。不过实际项目中，我一般只在完全展开和完全收起两个节点做切换，减少频繁重绘带来的掉帧风险。

5. Android 15 和 Edge-to-Edge 带来的新变化

5.1 强制 Edge-to-Edge 后navigationBarColor为什么会失效

如果你把targetSdkVersion升到 35 或以上，那么 Android 15 会强制开启 Edge-to-Edge。在传统模式下，开发者可以通过window.navigationBarColor直接控制导航栏背景色。但在强制 Edge-to-Edge 下，系统希望应用把内容绘制到系统栏后面，系统栏默认透明，自然就不接受你去设置一个纯色的navigationBarColor。

如果你的弹窗恰好跑在这样的设备上，你会发现老代码里setNavigationBarColor明明写了却不生效，导航栏看起来总是透出背后内容，甚至出现颜色混乱的情况。

这种时候，好的应对方式不再是“不透明的纯色底”，而是让弹窗的内容区自己把底部铺满，然后在内容根部留出系统导航栏区域的安全边距。

5.2 高版本推荐写法：透明导航栏 + 内容自身延伸

Edge-to-Edge 下的最佳实践是让 BottomSheet 内容延伸到系统栏下方，再由布局自己处理底部边距。

一种简单的做法是在 Fragment 内容布局的根部设置fitsSystemWindows = true。不过BottomSheetDialogFragment的情况比较特殊，内容区本身会滚动，所以我们更常用的是在布局最底部加一个高度等于导航栏 inset 的占位空间。

在代码里，通过WindowInsets获取底部的 inset：

view.setOnApplyWindowInsetsListener { v, insets -> val bottomInset = insets.getInsets(WindowInsetsCompat.Type.systemBars()).bottom v.updatePadding(bottom = bottomInset) insets }

颜色层面，由于系统栏透明，底部真正显示的是你 BottomSheet 布局末端延伸过去的颜色。只要弹窗背景色和页面底部一致，视觉上就自然衔接了。

导航栏图标深浅色依然通过WindowInsetsControllerCompat设置，这一点没有变。

5.3 临时退出 Edge-to-Edge 的兼容开关

Android 15 为还在适配期的应用保留了一个清单/主题层面的开关：windowOptOutEdgeToEdgeEnforcement。如果团队实在来不及改造布局，可以通过在主题里设置它来临时退出强制 Edge-to-Edge：

<style name="Theme.App.BottomSheetDialog.Base" parent="Theme.MaterialComponents.Light.BottomSheetDialog"> <item name="android:windowOptOutEdgeToEdgeEnforcement">true</item> </style>

这个属性可以暂时让旧代码继续工作，但需要考虑它只是一个过渡方案。如果产品要求长期适配新系统，还是在布局层处理 insets 更靠谱。我一般只会在线上热修复期间临时加上，正式版本一律走新方案。

5.4 兼容不同系统版本的一套代码思路

因为不少 App 的最低版本还在 API 21 或 API 24 附近，我们没法直接扔了旧 AP。这里我建议把新旧逻辑封装在一个方法里，根据当前系统版本来分流。

思路大致是：

• 在 API 21 到 API 34 之间，沿用传统navigationBarColor方式。
• 在 API 35 或 targetSdk 35 以上且检测到 Edge-to-Edge 生效时，不再设置纯色，而是让内容区延伸 + 控制前景图标深度。
• 无论哪个版本，都统一用WindowInsetsControllerCompat去控制图标明暗。

这样做的好处是，即使系统行为变了，代码改动面依然很小，不会因为 Android 版本升级导致整个弹窗样式全部失控。

6. 典型问题排查与避坑清单

6.1 导航栏背景改成浅色后，按钮和手势条看不见

这是最经典的坑之一。

原因很简单：只设置了navigationBarColor，没有同时把图标模式切到深色。

排查时看两处：一是android:windowLightNavigationBar在主题里是否为true；二是运行时有没有用WindowInsetsControllerCompat把isAppearanceLightNavigationBars设为true。两个地方都检查一遍，图标颜色就会正常。

6.2 在 onCreateView 里设置导航栏颜色没生效

我遇到过不少例子，代码写在onCreateView里，运行起来前面的弹窗可能生效，切到别的页面再回来就不行了。

原因前面提过：Dialog窗口没有完全初始化。此时调用dialog?.window可能为空，或者 Window 还没有准备接受布局属性。

解决办法：把设置代码放到onStart或更晚。如果你确实需要在内容布局生成时就知道颜色，可以先用变量存下来，等窗口 ready 后再应用。

6.3 设置了FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS后反而出现一层半透明遮罩

这个 flag 本身没问题，但需要配合clearFlags(FLAG_TRANSLUCENT_NAVIGATION)使用。

如果不清除后者，系统仍会认为你的 Window 需要半透明导航栏背景，于是叠加一层灰色遮罩到纯色上面，看起来就不是你设的颜色了。这在 API 21~29 设备上尤其明显。

6.4 设置了透明导航栏，但底部内容被手势条遮挡

如果你决定走 Edge-to-Edge 方案，让内容延伸到系统栏，但内容布局没有处理底部 inset，那么最后的按钮或列表倒数第一项就会顶到导航栏下面，甚至被系统手势区盖住。

处理方式分两种：

• 给滑动内容底部增加navigationBars()inset 的 padding；
• 在不需要延伸到底的弹窗里，让系统自动 fit，避免内容进入系统栏区域。

例如在CoordinatorLayout的底部 sheet 内容加了fitsSystemWindows=true，列表滚动到底部时会自动留足空白，不会挡住最后一行。

6.5 部分国产 ROM 上设置丢失

有些国产 ROM 对系统栏的管理比较激进，锁屏再解锁、切后台再回来，导航栏颜色会被系统重新覆盖回去。

遇到这种问题，除了在onStart里设置一次，还需要在onResume或其他窗口重获焦点的时机补一次。可以监听onWindowFocusChanged，或者干脆在onResume里重新调用一遍工具方法，成本很低，但能覆盖绝大多数场景。

补充一个细节：如果弹窗里面的 WebView 或者视频播放器抢占了焦点，系统栏状态也可能变化，最好在内容切换后再应用一次样式。

6.6 深色模式适配时只改了一个色值

如果你的 App 支持深色模式，仅提供colors.xml中的默认颜色是不够的。系统在夜间模式下，弹窗背景可能是#121212这种深色，可你的导航栏颜色还留在浅色主题里，很容易出现上下亮度分裂。

正确做法是建立一套完整的“浅色/深色”色板资源，在values-night目录下覆盖导航栏背景色和图标明暗开关。不要指望运行时去判断uiMode，因为导航栏色值在系统切换夜间模式时可能没有足够的时机同步更新，资源目录的切换是更稳定的方案。

7. 我的一点经验收尾

做这种系统栏细节调整，最容易踩坑的其实不是不会调用 API，而是没想清楚自己的弹窗和系统栏之间到底谁覆盖谁。弹窗高度变一点、圆角半径改一点、主题换一下，最终效果都会不同。我习惯在正式写 Fragment 前先画清楚：弹窗在屏幕上的位置、是否扩展到状态栏、是否扩展到导航栏、底部有没有操作按钮。这四个问题回答完了，颜色方案基本就不会跑偏。

最后一个小技巧：如果你需要在多个BottomSheetDialogFragment子类里复用同一套逻辑，不建议每个 Fragment 都复制一份onStart代码。把“主题选择、导航栏颜色、图标明暗、边缘到边缘适配”一起封装在基类或者一个 helper 里，页面通过枚举或参数告诉它“我要亮底深图标”还是“暗底浅图标”，后续维护会轻松很多。实测下来这样处理，即便团队后来新增六七种弹窗，也很难再看到导航栏颜色乱飞的问题。