maui-safe-area
.NET MAUI safe area and edge-to-edge layout guidance for .NET 10+. Covers the new SafeAreaEdges property, SafeAreaRegions enum, per-edge control, keyboard avoidance, Blazor Hybrid CSS safe areas, migration from legacy iOS-only APIs, and platform-specific behavior for Android, iOS, and Mac Catalyst. USE FOR: "safe area", "edge-to-edge", "SafeAreaEdges", "SafeAreaRegions", "keyboard avoidance", "notch insets", "status bar overlap", "iOS safe area", "Android edge-to-edge", "content behind status bar", "UseSafeArea migration", "soft input keyboard", "IgnoreSafeArea replacement". DO NOT USE FOR: general layout or grid design (use Grid and StackLayout), app lifecycle handling (use maui-app-lifecycle), theming or styling (use maui-theming), or Shell navigation structure.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- maui-safe-area
- license
- MIT
- description
- .NET MAUI safe area and edge-to-edge layout guidance for .NET 10+. Covers the new SafeAreaEdges property, SafeAreaRegions enum, per-edge control, keyboard avoidance, Blazor Hybrid CSS safe areas, migration from legacy iOS-only APIs, and platform-specific behavior for Android, iOS, and Mac Catalyst. USE FOR: "safe area", "edge-to-edge", "SafeAreaEdges", "SafeAreaRegions", "keyboard avoidance", "notch insets", "status bar overlap", "iOS safe area", "Android edge-to-edge", "content behind status bar", "UseSafeArea migration", "soft input keyboard", "IgnoreSafeArea replacement". DO NOT USE FOR: general layout or grid design (use Grid and StackLayout), app lifecycle handling (use maui-app-lifecycle), theming or styling (use maui-theming), or Shell navigation structure.
02 资源文件 1
- 参考文档references/safe-area-api.md8.4 KB
03 SKILL.md 正文
Safe Area & Edge-to-Edge Layout (.NET 10+)
.NET 10 introduces a brand-new, cross-platform safe area API that replaces the legacy iOS-only UseSafeArea and the layout-level IgnoreSafeArea properties. The new SafeAreaEdges property and SafeAreaRegions flags enum give you per-edge, per-control safe area management on Android, iOS, and Mac Catalyst from a single API surface.
This is new API surface in .NET 10. If the project targets .NET 9 or earlier, these APIs do not exist. Guide the developer to the legacy
ios:Page.UseSafeAreaandLayout.IgnoreSafeAreaproperties instead.
When to Use
- Content overlaps status bar, notch, Dynamic Island, or home indicator after upgrading to .NET 10
- Implementing edge-to-edge / immersive layouts (photo viewers, video players, maps)
- Keyboard avoidance for chat or form UIs
- Migrating from
ios:Page.UseSafeArea,Layout.IgnoreSafeArea, orWindowSoftInputModeAdjust.Resize - Blazor Hybrid apps that need CSS
env(safe-area-inset-*)coordination - Mixed layouts with an edge-to-edge header but a safe-area-respecting body
When Not to Use
- Projects targeting .NET 9 or earlier — use the legacy iOS-specific APIs
- General page layout questions unrelated to system bars or keyboard — use standard layout guidance
- App lifecycle or navigation structure — use maui-app-lifecycle or Shell guidance
- Theming or visual styling — use the maui-theming skill
Inputs
- Target framework: must be
net10.0-*or later for the new APIs - Target platforms: Android, iOS, Mac Catalyst (Windows does not have system bar insets)
- UI approach: XAML/C#, Blazor Hybrid, or MauiReactor
SafeAreaRegions Enum
[Flags]
public enum SafeAreaRegions
{
None = 0, // Edge-to-edge — no safe area padding
SoftInput = 1 << 0, // Pad to avoid the on-screen keyboard
Container = 1 << 1, // Stay inside status bar, notch, home indicator
Default = -1, // Use the platform default for the control type
All = 1 << 15 // Respect all safe area insets (most restrictive)
}
SoftInput and Container are combinable flags:
SafeAreaRegions.Container | SafeAreaRegions.SoftInput = respect system bars and keyboard.
SafeAreaEdges Struct
public readonly struct SafeAreaEdges
{
public SafeAreaRegions Left { get; }
public SafeAreaRegions Top { get; }
public SafeAreaRegions Right { get; }
public SafeAreaRegions Bottom { get; }
// Uniform — same value for all four edges
public SafeAreaEdges(SafeAreaRegions uniformValue)
// Horizontal / Vertical
public SafeAreaEdges(SafeAreaRegions horizontal, SafeAreaRegions vertical)
// Per-edge
public SafeAreaEdges(SafeAreaRegions left, SafeAreaRegions top,
SafeAreaRegions right, SafeAreaRegions bottom)
}
Static presets: SafeAreaEdges.None, SafeAreaEdges.All, SafeAreaEdges.Default.
XAML Type Converter
Follows Thickness-like comma-separated syntax:
<!-- Uniform -->
SafeAreaEdges="Container"
<!-- Horizontal, Vertical -->
SafeAreaEdges="Container, SoftInput"
<!-- Left, Top, Right, Bottom -->
SafeAreaEdges="Container, Container, Container, SoftInput"
Control Defaults
| Control | Default | Notes |
|---|---|---|
ContentPage |
None |
Edge-to-edge. Breaking change from .NET 9 on Android. |
Layout (Grid, StackLayout, etc.) |
Container |
Respects bars/notch, flows under keyboard |
ScrollView |
Default |
iOS maps to automatic content insets. Only Container and None take effect. |
ContentView |
None |
Inherits parent behavior |
Border |
None |
Inherits parent behavior |
Breaking Changes from .NET 9
ContentPage default changed to None
In .NET 9, Android ContentPage behaved like Container. In .NET 10, the default is None on all platforms. If your Android content goes behind the status bar after upgrading:
<!-- .NET 10 default — content extends under status bar -->
<ContentPage>
<!-- Restore .NET 9 Android behavior -->
<ContentPage SafeAreaEdges="Container">
WindowSoftInputModeAdjust.Resize removed
If you used WindowSoftInputModeAdjust.Resize in .NET 9, replace it with SafeAreaEdges="All" on the ContentPage for equivalent keyboard avoidance.
Usage Patterns
Edge-to-edge immersive content
Set None on both page and layout — layouts default to Container:
<ContentPage SafeAreaEdges="None">
<Grid SafeAreaEdges="None">
<Image Source="background.jpg" Aspect="AspectFill" />
<VerticalStackLayout Padding="20" VerticalOptions="End">
<Label Text="Overlay text" TextColor="White" FontSize="24" />
</VerticalStackLayout>
</Grid>
</ContentPage>
Forms and critical content
<ContentPage SafeAreaEdges="All">
<VerticalStackLayout Padding="20">
<Label Text="Safe content" FontSize="18" />
<Entry Placeholder="Enter text" />
<Button Text="Submit" />
</VerticalStackLayout>
</ContentPage>
Keyboard-aware chat layout
<ContentPage>
<Grid RowDefinitions="*,Auto"
SafeAreaEdges="Container, Container, Container, SoftInput">
<ScrollView Grid.Row="0">
<VerticalStackLayout Padding="20" Spacing="10">
<Label Text="Messages" FontSize="24" />
</VerticalStackLayout>
</ScrollView>
<Border Grid.Row="1" BackgroundColor="LightGray" Padding="20">
<Grid ColumnDefinitions="*,Auto" Spacing="10">
<Entry Placeholder="Type a message..." />
<Button Grid.Column="1" Text="Send" />
</Grid>
</Border>
</Grid>
</ContentPage>
Mixed: edge-to-edge header + safe body + keyboard footer
<ContentPage SafeAreaEdges="None">
<Grid RowDefinitions="Auto,*,Auto">
<Grid BackgroundColor="{StaticResource Primary}">
<Label Text="App Header" TextColor="White" Margin="20,40,20,20" />
</Grid>
<ScrollView Grid.Row="1" SafeAreaEdges="Container">
<!-- Use Container, not All — ScrollView only honors Container and None -->
<VerticalStackLayout Padding="20">
<Label Text="Main content" />
</VerticalStackLayout>
</ScrollView>
<Grid Grid.Row="2" SafeAreaEdges="SoftInput"
BackgroundColor="LightGray" Padding="20">
<Entry Placeholder="Type a message..." />
</Grid>
</Grid>
</ContentPage>
Programmatic (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)
};
Decision Framework
| Scenario | SafeAreaEdges value |
|---|---|
| Forms, critical inputs | All |
| Photo viewer, video player, game | None (on page and layout) |
| Scrollable content with fixed header/footer | Container |
| Chat/messaging with bottom input bar | Per-edge: Container, Container, Container, SoftInput |
| Blazor Hybrid app | None on page; CSS env() for insets |
Blazor Hybrid Integration
For Blazor Hybrid apps, let CSS handle safe areas to avoid double-padding.
- Page stays edge-to-edge (default in .NET 10):
<ContentPage SafeAreaEdges="None">
<BlazorWebView HostPage="wwwroot/index.html">
<BlazorWebView.RootComponents>
<RootComponent Selector="#app" ComponentType="{x:Type local:Routes}" />
</BlazorWebView.RootComponents>
</BlazorWebView>
</ContentPage>
- Add
viewport-fit=coverinindex.html:
<meta name="viewport" content="width=device-width, initial-scale=1.0,
maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
- Use CSS
env()functions:
body {
padding-top: env(safe-area-inset-top);
padding-bottom: env(safe-area-inset-bottom);
padding-left: env(safe-area-inset-left);
padding-right: env(safe-area-inset-right);
}
Available CSS environment variables: env(safe-area-inset-top), env(safe-area-inset-bottom), env(safe-area-inset-left), env(safe-area-inset-right).
Migration from Legacy APIs
| Legacy (.NET 9 and earlier) | New (.NET 10+) |
|---|---|
ios:Page.UseSafeArea="True" |
SafeAreaEdges="Container" |
Layout.IgnoreSafeArea="True" |
SafeAreaEdges="None" |
WindowSoftInputModeAdjust.Resize |
SafeAreaEdges="All" on ContentPage |
The legacy properties still compile but are marked obsolete. IgnoreSafeArea="True" maps internally to SafeAreaRegions.None.
<!-- .NET 9 (legacy, iOS-only) -->
<ContentPage xmlns:ios="clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;assembly=Microsoft.Maui.Controls"
ios:Page.UseSafeArea="True">
<!-- .NET 10+ (cross-platform) -->
<ContentPage SafeAreaEdges="Container">
Platform-Specific Behavior
iOS & Mac Catalyst
- Safe area insets cover: status bar, navigation bar, tab bar, notch/Dynamic Island, home indicator
SoftInputincludes the keyboard when visible- Insets update automatically on rotation and UI visibility changes
ScrollViewwithDefaultmaps toUIScrollViewContentInsetAdjustmentBehavior.Automatic
Transparent navigation bar for content behind the nav bar:
<Shell Shell.BackgroundColor="#80000000" Shell.NavBarHasShadow="False" />
Android
- Safe area insets cover: system bars (status/navigation) and display cutouts
SoftInputincludes the soft keyboard- MAUI uses
WindowInsetsCompatandWindowInsetsAnimationCompatinternally - Behavior varies by Android version and OEM edge-to-edge settings
Common Pitfalls
-
Forgetting to set
Noneon the layout too.ContentPage SafeAreaEdges="None"makes the page edge-to-edge, but child layouts default toContainerand still pad inward. SetNoneon both page and layout for truly immersive content. -
Using
SoftInputdirectly on ScrollView. ScrollView manages its own content insets and ignoresSoftInput. Wrap the ScrollView in a Grid or StackLayout and applySoftInputthere. -
Confusing
DefaultwithNone.Defaultmeans "platform default for this control type" — on ScrollView (iOS) this enables automatic content insets.Nonemeans "no safe area padding at all." -
Double-padding in Blazor Hybrid. Setting
SafeAreaEdges="Container"on the page and using CSSenv(safe-area-inset-*)results in doubled insets. Pick one approach — CSS is recommended for Blazor. -
Missing
viewport-fit=coverin Blazor. Without this meta tag, CSSenv(safe-area-inset-*)values are always zero on iOS. -
Assuming .NET 9 behavior on Android. After upgrading to .NET 10, Android
ContentPagedefaults toNone(was effectivelyContainer). AddSafeAreaEdges="Container"to restore the previous behavior. -
Using legacy
ios:Page.UseSafeAreain new code. The old API is iOS-only and obsolete. Always useSafeAreaEdgesfor cross-platform safe area management.
Checklist
- [ ] Android upgrade:
SafeAreaEdges="Container"added if content goes under status bar - [ ] Edge-to-edge:
Noneset on both page and layout - [ ] ScrollView keyboard avoidance uses wrapper Grid, not ScrollView's own
SafeAreaEdges - [ ] Blazor Hybrid: using either XAML or CSS safe areas, not both
- [ ]
viewport-fit=coverin Blazor'sindex.html<meta viewport>tag - [ ] Legacy
UseSafeArea/IgnoreSafeAreamigrated toSafeAreaEdges
04 同仓库更多 Skills
system-text-json-net11
Provides guidance on new System.Text.Json APIs introduced in .NET 11. It covers typed JsonTypeInfo access via GetTypeInfo<T> and TryGetTypeInfo<T> on JsonSerializerOptions, and the new JsonNamingPolicy.PascalCase static property. Use when serializing or deserializing JSON in .NET 11 applications and needing typed metadata access or PascalCase property naming.
nuget-trusted-publishing
Set up NuGet trusted publishing (OIDC) on a GitHub Actions repo — replaces long-lived API keys with short-lived tokens. USE FOR: trusted publishing, NuGet OIDC, keyless NuGet publish, migrate from NuGet API key, NuGet/login, secure NuGet publishing. DO NOT USE FOR: publishing to private feeds or Azure Artifacts (OIDC is nuget.org only). INVOKES: shell (powershell or bash), edit, create, ask_user for guided repo setup.
dotnet-pinvoke
Correctly call native (C/C++) libraries from .NET using P/Invoke and LibraryImport. Covers function signatures, string marshalling, memory lifetime, SafeHandle, and cross-platform patterns. USE FOR: writing new P/Invoke or LibraryImport declarations, reviewing or debugging existing native interop code, wrapping a C or C++ library for use in .NET, diagnosing crashes, memory leaks, or corruption at the managed/native boundary. DO NOT USE FOR: COM interop, C++/CLI mixed-mode assemblies, or pure managed code with no native dependencies.
csharp-scripts
Run file-based C# apps with the .NET CLI when the user explicitly wants C#/.NET code without creating a project. Use for C# language/API experiments, one-file C# apps, small multi-file C# apps composed with `#:include`/`#:exclude`, or C# file-based apps linked with `#:ref`. Do not use for language-agnostic throwaway scripts, generic computations, Python/PowerShell-style automation, full projects, or existing app integration.
thread-abort-migration
Guides migration of .NET Framework Thread.Abort usage to cooperative cancellation in modern .NET. USE FOR: modernizing code that calls Thread.Abort, catching ThreadAbortException, replacing Thread.ResetAbort, replacing Thread.Interrupt for thread termination, resolving PlatformNotSupportedException or SYSLIB0006 after retargeting to .NET 6+, migrating ASP.NET Response.End or Response.Redirect(url, true) which internally call Thread.Abort. DO NOT USE FOR: code that only uses Thread.Join, Thread.Sleep, or Thread.Start without any abort, interrupt, or ThreadAbortException usage — these APIs work identically in modern .NET and need no migration. Also not for projects staying on .NET Framework, or Thread.Abort usage inside third-party libraries you do not control.
migrate-nullable-references
Enable nullable reference types in a C# project and systematically resolve all warnings. USE FOR: adopting NRTs in existing codebases, file-by-file or project-wide migration, fixing CS8602/CS8618/CS86xx warnings, annotating APIs for nullability, cleaning up null-forgiving operators, upgrading dependencies with new nullable annotations. DO NOT USE FOR: projects already fully migrated with zero warnings (unless auditing suppressions), fixing a handful of nullable warnings in code that already has NRTs enabled, suppressing warnings without fixing them, C# 7.3 or earlier projects. INVOKES: Get-NullableReadiness.ps1 scanner script.