mcpField
M
maui-safe-area

maui-safe-area

github.com/davidortinau设计与 UI17654 次安装16 周前更新
代码仓库

关于 maui-safe-area

面向 .NET MAUI 开发者的安全区域指南，涵盖 .NET 10+ 的行为变化与迁移。说明如何为页面和控件选择安全区域设置，并规避平台相关的布局及键盘问题。

主要功能

  1. 01.NET 9 到 10 迁移指导
  2. 02按布局场景选择 SafeAreaEdges
  3. 03平台特定布局注意事项
  4. 04Blazor Hybrid 安全区域指导
  5. 05设备与屏幕测试清单

适用场景

  1. 01升级后修复 Android 内容遮挡状态栏
  2. 02配置媒体视图的边缘到边缘显示
  3. 03让聊天输入栏在键盘弹出时保持可见
  4. 04避免 Blazor Hybrid 中安全区域内边距重复

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/davidortinau/maui-skills --skill maui-safe-area

安装后在 Claude Code 中输入/maui-safe-area确认已加载。

附带文件references/safe-area-api.md

详细介绍

安全区域 — 注意事项与最佳实践（.NET 10+）

破坏性变更

⚠️ .NET 9 → 10：ContentPage 的默认值已更改为 None

现在，ContentPage 在所有平台上默认采用延伸至边缘（None）的布局。在 .NET 9 中， Android 的 ContentPage 行为类似于 Container。如果升级后 Android 内容延伸到了 状态栏下方，请显式添加 SafeAreaEdges="Container"。


<ContentPage>


<ContentPage SafeAreaEdges="Container">
⚠️ 迁移 WindowSoftInputModeAdjust.Resize

如果你在 .NET 9 中使用了 WindowSoftInputModeAdjust.Resize，可能需要在 ContentPage 上设置 SafeAreaEdges="All"，以保持对键盘的避让。

常见注意事项

1. 布局默认值是 Container，而非 None

要实现真正的延伸至边缘布局，请在页面和布局上都设置 SafeAreaEdges="None"：


<ContentPage SafeAreaEdges="None">
    <Grid>
        <Image Source="bg.jpg" Aspect="AspectFill" />
    </Grid>
</ContentPage>


<ContentPage SafeAreaEdges="None">
    <Grid SafeAreaEdges="None">
        <Image Source="bg.jpg" Aspect="AspectFill" />
    </Grid>
</ContentPage>
2. 在 ScrollView 上设置 SoftInput 不起作用

ScrollView 会自行管理内容内边距。请改用 Grid/StackLayout 包裹它：


<ScrollView SafeAreaEdges="SoftInput">


<Grid SafeAreaEdges="Container, Container, Container, SoftInput">
    <ScrollView> ... </ScrollView>
</Grid>
3. Default 不等于 None

Default =“使用此控件类型的平台默认值。”None =“延伸至边缘。” 两者在 ScrollView 上差异很大（iOS 会将 Default 映射为自动内容内边距）。

4. Blazor Hybrid 的重复内边距

<ContentPage SafeAreaEdges="Container">
    <BlazorWebView ... />  


<ContentPage SafeAreaEdges="None">
    <BlazorWebView ... />
5. iOS Shell/NavigationPage 延伸至边缘

除非设置透明背景并隐藏分隔线，否则内容不会延伸到导航栏后方：

<Shell Shell.BackgroundColor="#80000000"
       Shell.NavBarHasShadow="False" />

决策指南

场景SafeAreaEdges 值
表单、关键输入项All
照片查看器、视频播放器、游戏None（页面和布局均需设置）
带固定页眉/页脚的可滚动内容Container
带底部输入栏的聊天/消息界面按边设置：Container, Container, Container, SoftInput
Blazor Hybrid 应用页面设为 None，使用 CSS env() 处理内边距

迁移快速参考

旧版（.NET 9）新版（.NET 10+）
ios:Page.UseSafeArea="True"SafeAreaEdges="Container"
IgnoreSafeArea="True"SafeAreaEdges="None"
WindowSoftInputModeAdjust.Resize在 ContentPage 上设置 SafeAreaEdges="All"

旧属性仍可使用，但已弃用。

最佳实践

  1. 将 SafeAreaEdges 与 Padding 结合使用——安全区域处理内边距，Padding 增加视觉间距：

    <ContentPage SafeAreaEdges="All">
    <VerticalStackLayout Padding="20">
        
    </VerticalStackLayout>
</ContentPage>

  2. 为不同控件分别设置，以适配混合布局（延伸至边缘的页眉 + 安全区域内的正文 + 能避让键盘的页脚）。

  3. 对于 Blazor Hybrid，优先使用 CSS env()，并将 SafeAreaEdges="None" 保留为默认设置。 在 <meta viewport> 标签中添加 viewport-fit=cover。

  4. 在带刘海的设备上测试（iPhone X+、Android 屏幕开孔设备）、横屏平板以及不同尺寸的屏幕。

检查清单

  • Android 升级：如果内容延伸到状态栏下方，则添加 SafeAreaEdges="Container"
  • 延伸至边缘：页面和布局上都设置为 None
  • ScrollView 键盘避让使用包装 Grid，而非 ScrollView 自身的 SafeAreaEdges
  • Blazor Hybrid：使用 XAML 或 CSS 安全区域方案之一，不要同时使用两者
  • 在 Blazor 的 index.html 的 <meta viewport> 标签中设置 viewport-fit=cover
  • 将旧版 UseSafeArea / IgnoreSafeArea 迁移为 SafeAreaEdges

评论

支持 Markdown