Edge-to-Edge Display in Capacitor Without Plugins

Capacitorアプリにエッジツーヨーディスプレイを実装しようとしている場合 Capacitorにはエッジツーヨーディスプレイの公式サポートがあります。 adjustMarginsForEdgeToEdge 設定オプション - ただし、広く文書化されていません。

多くの開発者は、Capacitor アプリでエッジツーヨーロードレイアウトに苦労しています。特にAndroid 15+を対象にすると、現代的なエッジツーヨーロードの見た目を実現するために、カスタムプラグインやCSSハックに頼ることがよくあります。しかし、より良い、ネイティブの方法があります。

Edge-to-Edge Displayとは何ですか。

Edge-to-edge displayは、アプリのコンテンツがシステムバー（ステータスバーとナビゲーションバー）後ろに延びるようにすることで、よりインマーシブで現代的なUI体験を実現します。Android 15から始めて、Googleはすべてのアプリにエッジツーヨーロードを標準として推進しています。

公式解決策: adjustMarginsForEdgeToEdge

Capacitorは、この目的のために、 adjustMarginsForEdgeToEdge 設定オプションを提供しています。この設定は、公式の__CAPGO_KEEP_0__設定ドキュメント official Capacitor config documentation設定方法

__CAPGO_KEEP_0__の

または capacitor.config.ts に追加してください。 capacitor.config.json:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  android: {
    adjustMarginsForEdgeToEdge: 'auto' // or 'force' or 'disable'
  }
};

export default config;

JSON形式で指定することもできます。

{
  "appId": "com.example.app",
  "appName": "My App",
  "webDir": "dist",
  "android": {
    "adjustMarginsForEdgeToEdge": "auto"
  }
}

設定オプション

この adjustMarginsForEdgeToEdge オプションは、3つの値を受け入れます:

1. `"auto"` (推奨)

adjustMarginsForEdgeToEdge: 'auto'

これが行うこと: Android 15+ と設定を自動で確認し、デバイスと設定に応じて余白を適切に調整します。 windowOptOutEdgeToEdgeEnforcement 適切なデバイスでエッジからエッジまで表示したい、かつ古いAndroidバージョンと互換性を維持したい開発者向け

これが行うこと: Androidバージョンや他の設定に関係なく、余白調整を強制します。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

__CAPGO_KEEP_0__ __CAPGO_KEEP_0__

最適なのは: Android 全バージョンで、端から端までの動作を実現したいアプリ向け。

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

何をするか: 自動マージン調整を完全に無効にする。

最適なのは: 端から端までのレイアウトを手動で管理したい、アプリが端から端までの動作を実現したくない場合。

注意: 現在はデフォルトですが、__CAPGO_KEEP_0__ 8 では "disable" Android 15 以降の端から端までの表示をデフォルトの動作として強制するため、Google は、端から端までのレイアウトを適切に管理していないアプリが、UI 問題を経験する可能性があります。 "auto" in Capacitor 8.

この問題は、以下のUI 問題を引き起こす可能性があります:

UI 問題の例:

システムバーの背後にあるコンテンツ
不自然なスペースとパディング
デバイス間で一貫しない外観
ユーザー体験が悪い

公式の adjustMarginsForEdgeToEdge configを使用すると、カスタム code を必要とせずに、これらの変更を適切に処理するようにアプリが管理されることを保証します。

完全な例

ここに、最新の Capacitor アプリの完全な例の設定があります。

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'My Awesome App',
  webDir: 'www',
  server: {
    androidScheme: 'https'
  },
  android: {
    // Enable edge-to-edge automatically on supported devices
    adjustMarginsForEdgeToEdge: 'auto',

    // Other Android config options...
    backgroundColor: '#ffffff'
  }
};

export default config;

CSSの考慮事項

エッジをエッジに表示する場合、安全なエリアを処理するために、CSSを追加する必要がある場合があります。

/* Add padding for system bars */
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);
}

/* Or use viewport-fit */
meta[name="viewport"] {
  content: "width=device-width, initial-scale=1, viewport-fit=cover";
}

設定をテストする

設定を適用した後 adjustMarginsForEdgeToEdge, アプリをテストする:

Android 15以上のデバイス - システムバーを尊重するコンテンツが適切に機能することを確認する
古いAndroidバージョン - バックワード互換性を確保する
異なる画面サイズ - デバイス間でレイアウトが機能することを確認する
ライトとダークのテーマ - 両方のテーマモードをテストする

よくある間違いを避ける

このような第三者のプラグインを使用しない

あなたは必要ない第三者のプラグインのようなもの capacitor-edge-to-edge または同様のもの。ネイティブの設定では、この問題をきれいに処理します。

手動実装と組み合わせないでください。

Capacitorを使用している場合、 adjustMarginsForEdgeToEdge手動でウィンドウのインセットを処理している場合やCSSのハックを追加している場合、すべて削除してください。

セーフエリアのCSSを忘れないでください。

設定はマージンを調整しますが、正しいコンテンツのパディングを得るには、CSSのセーフエリアのインセットを使用する必要があります。

移行ガイド

Edge-to-edgeのプラグインやハックを使用している場合、

依存関係からEdge-to-edgeのプラグインを削除してください。 設定オプションを追加してください。
Capacitorを使用している場合、 to your capacitor.config.ts
Clean and rebuild Android プロジェクトを再構築する
しっかりテストする ターゲットデバイスでテストする

# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..

# Rebuild
npx cap copy android
npx cap open android

将来の準備

Capacitor 8 をデフォルト値にすることは覚えておくべきだ。準備するには: "auto" テストする

今すぐ "auto" 問題を早期に発見するために CSS を更新する
安全なエリアを適切に処理するために Future-Proofing
レイアウトを確認する エッジ・トゥ・エッジ有効デバイスで

追加リソース

まとめ

Edge-to-edge display in Capacitor doesn’t require plugins, hacks, or complicated workarounds. The adjustMarginsForEdgeToEdge 設定オプションは、公式サポートを受け、将来性のあるクリーンでネイティブなソリューションを提供します。

まず "auto" ほとんどのアプリでは、デバイスをテストし、適切なセーフエリアCSSを追加し、Android 15以降に対応するために最小限の努力でアプリを準備します。

質問や問題が発生した場合は? Capacitorコミュニティと公式ドキュメントは追加のヘルプのための素晴らしいリソースです。

Capacitorにプラグインなしでエッジツーヨーディスプレイ