.NET MAUI 10+…

在 .NET 10+ MAUI 应用中出现内容被状态栏、刘海、Dynamic Island、Home 指示条或软键盘遮挡，或需要边到边、键盘避让、Blazor Hybrid 安全区处理时使用。

适用场景

解决思路

1. 确认目标框架为 net10.0-* 或更高；若项目是 .NET 9 或更早，改用 legacy ios:Page.UseSafeArea 和 Layout.IgnoreSafeArea，因为新 API 不存在。
2. 在 Android、iOS、Mac Catalyst 上用新的 SafeAreaEdges 属性和 SafeAreaRegions flags 枚举按边、按控件管理安全区域；Windows 没有系统栏 insets。
3. 使用 SafeAreaRegions 取值：None=0 表示边到边、无安全区 padding；SoftInput=1 << 0 表示避让屏幕键盘；Container=1 << 1 表示留在状态栏、刘海、Home 指示条内；Default=-1 表示该控件类型的平台默认；All=1 << 15 表示尊重所有安全区 insets（最严格）。
4. 组合 SoftInput 与 Container：SafeAreaRegions.Container | SafeAreaRegions.SoftInput 表示同时尊重系统栏和键盘。
5. 使用 SafeAreaEdges 结构：Left、Top、Right、Bottom 分别设置 SafeAreaRegions；构造函数支持统一值、水平/垂直值、四边分别值；静态预设为 SafeAreaEdges.None、SafeAreaEdges.All、SafeAreaEdges.Default。
6. 在 XAML 中用类似 Thickness 的逗号分隔语法：统一值 SafeAreaEdges="Container"；水平,垂直 SafeAreaEdges="Container, SoftInput"；左,上,右,下 SafeAreaEdges="Container, Container, Container, SoftInput"。
7. 检查控件默认值：ContentPage 默认 None（Android 从 .NET 9 到 .NET 10 的破坏性变更）；Layout（Grid、StackLayout 等）默认 Container；ScrollView 默认 Default，iOS 映射为 automatic content insets，且只有 Container 和 None 生效；ContentView 默认 None 并继承父行为；Border 默认 None 并继承父行为。
8. 升级到 .NET 10 后，如果 Android 内容跑到状态栏下方，给 ContentPage 加 SafeAreaEdges="Container" 以恢复 .NET 9 Android 行为。
9. WindowSoftInputModeAdjust.Resize 仍存在且未标记过时，但仅限 Android；跨平台键盘避让优先在 ContentPage 上用 SafeAreaEdges="All"（或 SoftInput region）。
10. 实现边到边沉浸内容时，在 page 和 layout 都设置 None，因为 layout 默认是 Container；例如 ContentPage SafeAreaEdges="None" 且内部 Grid SafeAreaEdges="None"。
11. 表单和关键内容使用 ContentPage SafeAreaEdges="All"，让内容避开所有安全区。
12. 键盘感知聊天布局：在 Grid 上设置 SafeAreaEdges="Container, Container, Container, SoftInput"（四边分别为 Container, Container, Container, SoftInput），或按需在底部边设置 SoftInput。
13. 混合布局：ContentPage 设 SafeAreaEdges="None" 实现 edge-to-edge header；中间 ScrollView 设 SafeAreaEdges="Container"，不要用 All，因为 ScrollView 只认 Container 和 None；底部输入区 Grid 设 SafeAreaEdges="SoftInput"。
14. 编程式 C# 设置：var page = new ContentPage { SafeAreaEdges = SafeAreaEdges.All }; var grid = new Grid { SafeAreaEdges = new SafeAreaEdges(left: SafeAreaRegions.Container, top: SafeAreaRegions.Container, right: SafeAreaRegions.Container, bottom: SafeAreaRegions.SoftInput) };
15. 按决策框架选择：表单/关键输入用 All；照片查看器/视频播放器/游戏在 page 和 layout 都用 None；带固定页头/页脚的可滚动内容用 Container；聊天/消息底部输入栏用四边 Container, Container, Container, SoftInput；Blazor Hybrid 在 page 用 None，并用 CSS env() 处理 insets。
16. Blazor Hybrid：页面保持 edge-to-edge，即 ContentPage SafeAreaEdges="None"；在 index.html 的 viewport meta 中加入 viewport-fit=cover；用 CSS env(safe-area-inset-top)、env(safe-area-inset-bottom)、env(safe-area-inset-left)、env(safe-area-inset-right) 添加 padding；选择 CSS 或 XAML 其中一种安全区方案，避免双重 padding。
17. 迁移旧 API：ios:Page.UseSafeArea="True" 改为 SafeAreaEdges="Container"；Layout.IgnoreSafeArea="True" 改为 SafeAreaEdges="None"；WindowSoftInputModeAdjust.Resize 改为 ContentPage SafeAreaEdges="All"。旧属性仍可编译但已过时；IgnoreSafeArea="True" 内部映射到 SafeAreaRegions.None；新代码不要使用旧 ios:Page.UseSafeArea。
18. iOS & Mac Catalyst 注意：安全区 insets 覆盖 status bar、navigation bar、tab bar、notch/Dynamic Island、home indicator；SoftInput 在键盘可见时包含键盘；旋转和 UI 可见性变化时 insets 自动更新；ScrollView 的 Default 映射为 UIScrollViewContentInsetAdjustmentBehavior.Automatic；如需内容在导航栏后，可用 Shell Shell.BackgroundColor="#80000000" Shell.NavBarHasShadow="False"。
19. Android 注意：安全区 insets 覆盖系统栏（status/navigation）和 display cutouts；SoftInput 包含软键盘；MAUI 内部使用 WindowInsetsCompat 和 WindowInsetsAnimationCompat；行为随 Android 版本和 OEM edge-to-edge 设置变化。
20. 避免常见陷阱：忘记在 layout 也设 None；在 ScrollView 上直接用 SoftInput（应包在 Grid 或 StackLayout 上再应用）；混淆 Default 与 None；Blazor Hybrid 中 XAML 与 CSS 双重 padding；Blazor 缺少 viewport-fit=cover 导致 iOS env(safe-area-inset-*) 为 0；假设 Android 仍保持 .NET 9 行为；在新代码中使用旧 ios:Page.UseSafeArea。
21. 完成后检查：Android 升级后若内容到状态栏下，已加 SafeAreaEdges="Container"；edge-to-edge 时 page 和 layout 都已设 None；ScrollView 键盘避让用 wrapper Grid 而非 ScrollView 自身 SafeAreaEdges；Blazor Hybrid 只用 XAML 或 CSS 一种安全区；index.html 的 meta viewport 有 viewport-fit=cover；旧 UseSafeArea/IgnoreSafeArea 已迁移到 SafeAreaEdges。

适用边界 · 注意事项

• 项目目标为 .NET 9 或更早时不要使用新 SafeAreaEdges/SafeAreaRegions，改用 legacy ios:Page.UseSafeArea 和 Layout.IgnoreSafeArea。
• 与系统栏或键盘无关的普通页面布局、Grid/StackLayout 设计不要用本经验，应使用标准布局指导。
• 应用生命周期、导航结构、主题或视觉样式问题不要用本经验，应分别使用 maui-app-lifecycle、Shell 或 maui-theming 指导。