プラグインなしでCapacitorのエッジ・トゥ・エッジ表示を設定する

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設定方法

この設定を

または capacitor.config.ts __CAPGO_KEEP_0__ 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;

Or in JSON format:

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

設定オプション

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

1. `"auto"` (推奨)

adjustMarginsForEdgeToEdge: 'auto'

何をするか: Android 15 以降と設定を自動的にチェックします。デバイスと設定に基づいて余白を適切に調整します。 windowOptOutEdgeToEdgeEnforcement 最適な状況:

Android 15 以降をサポートするデバイスでエッジからエッジまで表示したいが、古い Android バージョンと互換性を維持したい開発者向け 何をするか:

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

Android バージョンや他の設定に関係なく、余白の調整を強制します。 __CAPGO_KEEP_0__

Best for: Android全バージョンで、端から端までの動作を実現したいアプリ

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

What it does: 自動マージン調整を完全に無効にする

Best for: 端から端までのレイアウトを手動で管理したい、アプリや端から端までの動作を実現したくないアプリ

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

Apps that handle edge-to-edge layout manually or don’t want edge-to-edge behavior.

Currently

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

公式の 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バージョン - バックワード互換性を確保する
異なる画面サイズ - デバイス間でレイアウトが機能することを確認する
ライトとダークのテーマ - 2つのテーマモードをテストする

一般的なミスを避ける

この用途ではプラグインを使用しないでください

第三のパーティー製プラグインを使う必要はありません capacitor-edge-to-edge または同様のもの。ネイティブの設定では、この問題をきれいに処理します。システムのチョームの詳細な制御が必要な場合は、有効化した後 adjustMarginsForEdgeToEdge, @capgo/capacitor-ナビゲーションバーと @capgo/ホームインジケーターネイティブの設定を置き換えずに補完することができます。

手動実装と混ぜないでください。

Capgoを使用している場合 adjustMarginsForEdgeToEdge,

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

安全なエリアのCSSを忘れないでください。

設定はマージンを調整しますが、適切なコンテンツのパディングのために、CSSの安全なエリアのインセットを使用する必要があります。

移行ガイドです。現在、エッジツーヘッジ用のプラグインやハックを使用している場合

エッジをエッジにしたプラグインを 依存関係から削除する
configオプションを 追加する capacitor.config.ts
Androidプロジェクトを クリーンアップしてビルドする
ターゲットデバイスで徹底的にテストする 将来の準備

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

# Rebuild
npx cap copy android
npx cap open android

__CAPGO_KEEP_0__ 8がデフォルト値になることを

Remember that Capacitor 8 will make "auto" 準備するには:

テストする "auto" 今 早期に問題を検出するために
CSSを更新 安全なエリアを適切に処理するために
レイアウトを確認 エッジツーヨーロッジアクティブデバイスで

追加リソース

結論

Capacitorでは、エッジツーヨーロッジアプリを実現するためにプラグイン、ハック、複雑なワークアラウンドは必要ありません。 adjustMarginsForEdgeToEdge 設定オプションは、クリーンでネイティブな解決策を提供し、公式にサポートされており、将来に耐える。

Start with "auto" ほとんどのアプリでは、デバイスを横断して徹底的にテストし、適切な安全エリアのCSSを追加してください。アプリは、最小限の努力でAndroid 15と以降に準備されます。

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

Edge-to-EdgeディスプレイをCapacitor Without Pluginsから始めてください。

Edge-to-Edgeディスプレイを__CAPGO_KEEP_0__ Without Pluginsで使用している場合、ネイティブメディアとインターフェイスの動作を計画するには、 Edge-to-EdgeディスプレイをCapacitor Without Pluginsで使用している場合、ネイティブメディアとインターフェイスの動作を計画するには、 を接続してください。 Using @capgo/capacitor-live-activities For the native capability in capgo/capacitor-live-activities, capgo/capacitor-live-activities For the implementation detail in capgo/capacitor-live-activities, Using capgo/capacitor-video-player For the native capability in Using capgo/capacitor-video-player, capgo/capacitor-video-player For the implementation detail in capgo/capacitor-video-player, and Using capgo/capacitor-native-navigation For the native capability in Using capgo/capacitor-native-navigation.

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