mcpField
M
maui-safe-area

maui-safe-area

github.com/davidortinauデザイン・UI17654 回インストール16 週間前に更新
リポジトリ

maui-safe-area について

.NET 10以降のセーフエリアの挙動と移行方法を扱う、.NET MAUI開発者向けスキルです。ページやコントロールのインセット設定を選び、プラットフォーム固有のレイアウトやキーボードの問題を避ける方法を説明します。

主な機能

  1. 01.NET 9から10への移行ガイド
  2. 02レイアウト別のSafeAreaEdges選択
  3. 03プラットフォーム固有の注意点
  4. 04Blazor Hybridのインセット指針
  5. 05デバイスと画面のテスト項目

活用シーン

  1. 01更新後にAndroidのステータスバー下への表示を修正
  2. 02メディアビューをエッジツーエッジに設定
  3. 03キーボード表示中もチャット入力欄を維持
  4. 04Blazor Hybridのセーフエリア余白の重複を防止

インストール

コマンドをコピーしてターミナルで実行します。

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

インストール後、Claude Code で/maui-safe-areaを入力して読み込まれたか確認します。

同梱ファイルreferences/safe-area-api.md

詳細

Safe Area — 注意点とベストプラクティス（.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. レイアウトの既定値は None ではなく Container

真のエッジツーエッジ表示にするには、ページとレイアウトの両方に 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.ResizeContentPage に 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 のキーボード回避には、ScrollView 自体の SafeAreaEdges ではなくラッパーの Grid を使用
  • Blazor Hybrid：XAML または CSS のどちらか一方でセーフエリアを使用し、両方は使用しない
  • Blazor の index.html の <meta viewport> タグに viewport-fit=cover を設定
  • 旧形式の UseSafeArea／IgnoreSafeArea を SafeAreaEdges に移行

コメント

Markdown 対応