PAYATHON 2026

.NET MAUI 10 的 TabBar 与 Android 导航按钮重叠，如何修复？

数据阿明

结论

先保留现有 TabBar 和 ShellContent 配置，检查 Android 系统栏主题、窗口设置及安全区域处理。提供的 XAML 主要定义标签内容和路由，仅凭这段代码无法确定重叠的根因。

.NET MAUI 10 调整了 Android 页面安全区域的默认行为，需要区分页面内容被系统导航栏遮挡，还是 Shell 原生 TabBar 本身被遮挡。页面的 SafeAreaEdges 可以处理前一种情况；后一种情况还要检查 Shell 所在窗口的布局和原生边距。

为什么升级后可能出现重叠？

.NET MAUI 10 中，Android 的 ContentPage 默认使用 SafeAreaEdges="None"，允许内容延伸到系统栏后方。显式设置 SafeAreaEdges="Container"，可以恢复接近 .NET 9 的页面避让行为。这是官方记录的行为变化，但不能据此认定它是当前 TabBar 重叠的唯一原因。Microsoft 安全区域文档

Android 的 edge-to-edge 布局也会影响结果。在 Android 15 及更高版本的设备上，面向 SDK 35 或更高版本的应用会采用 edge-to-edge 显示。窗口可以绘制到系统导航栏后方，交互控件则需要正确处理 WindowInsets。原问题没有提供 Android 版本和目标 SDK，需要核对这两个条件。Android edge-to-edge 文档

第一步：确认被遮挡的是页面还是 TabBar

如果页面底部的按钮、列表或其他内容被遮挡，可以在对应的 ContentPage 根节点设置安全区域。例如，将下面的属性合并到现有页面声明中，保留原有的 x:Class、命名空间和内容：

<ContentPage
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    SafeAreaEdges="Container">
    <!-- Existing page content -->
</ContentPage>

Container 用于避让系统栏和屏幕缺口；如果页面还需要避让软键盘，可以评估 All。这些设置的适用范围见 SafeAreaEdges 文档。

应在 LandingPage 等实际页面上配置，不要直接给 <TabBar> 或 <ShellContent> 添加这个属性。Shell 也没有可直接照搬上述示例的 SafeAreaEdges 属性。

如果页面内容正常，而 TabBar 的图标、文字或点击区域仍与 Android 导航按钮重叠，继续检查窗口和主题。

第二步：检查主题和系统栏定制

建议在调试分支中逐项停用以下定制，每次只改一项，然后重新启动应用：

  1. AppShell.xaml 中与系统栏有关的 Behavior，以及 Shell 的自定义样式。
  2. Platforms/Android/MainActivity.cs 中操作窗口标志、edge-to-edge 或 WindowInsets 的代码。
  3. Android 自定义主题中与全屏、透明系统栏有关的设置。
  4. 自定义 Shell renderer、handler 或 TabBar 外观跟踪器中的底部 Padding、Margin 和高度设置。

可以新建一个使用相同 MAUI 版本的 Shell 项目作为对照。先放入这五个标签，再逐项加入现有主题和系统栏定制，确认问题是由项目配置引起的，还是在默认配置下也能复现。

如果项目已经使用 CommunityToolkit.Maui 的 StatusBarBehavior，也应将它纳入排查。该 Behavior 用于控制状态栏颜色和样式，新增它不能作为恢复底部安全区域的通用方案。StatusBarBehavior 文档

第三步：检查原生 WindowInsets 处理

如果重叠只在自定义 Shell 渲染逻辑中出现，应检查系统导航栏的 inset 是否传递到了底部导航视图，以及是否被上层监听器提前消费。

Android 的 BottomNavigationView 通常会自动处理 insets。添加手动补偿前，先确认现有处理是否被覆盖；重复叠加系统边距也会造成布局错误。确有必要自定义处理时，应读取实际的 navigation bar inset，并以原始边距为基础更新，避免每次回调都累加。Android 原生视图边距处理说明

不要用固定的底部高度补偿整个应用。三键导航、手势导航、横竖屏和不同设备的系统导航区域可能不同。

如何确认修复有效？

至少检查三键导航和手势导航，逐个切换五个标签，并测试横竖屏及返回页面后的布局。确认 TabBar 的图标、文字和点击区域都能正常使用，底部也没有多出空白。

如果使用默认主题且没有自定义系统栏代码的最小项目仍能复现，记录实际的 Microsoft.Maui.Controls 版本、Android 版本和目标 SDK，对照 MAUI 的相关问题及修复记录。当前材料不足以认定某个具体版本存在缺陷，也不能保证单独设置页面的 SafeAreaEdges 就能修复原生 TabBar。

备注：内容仅供参考。