Edge-to-Edge Display in Capacitor Without Plugins

Capacitor アプリでエッジツーヨーロードディスプレイを実装するにはどうしたらいいですか? プラグイン、ワークアラウンド、ハックは必要ありません。 Capacitor にはエッジツーヨーロードディスプレイの公式サポートがあります。 adjustMarginsForEdgeToEdge 設定オプション - ただし、広く文書化されていません。

Capacitor アプリでエッジツーヨーロードレイアウトを実装するのは困難です。特に、Android 15+ を対象にすると、開発者は多くの場合、カスタムプラグインや CSS ハックを使用して、モダンなエッジツーヨーロードの見た目を実現します。

しかし、より適切でネイティブの方法があります。

エッジツーヨーロードディスプレイとは何ですか?

エッジツーヨーロードディスプレイは、アプリのコンテンツをシステムバー (ステータスバーとナビゲーションバー) の後ろに延長することで、よりインマーシブでモダンな UI エクスペリエンスを実現します。 Android 15 から、Google はすべてのアプリにエッジツーヨーロードを推進しています。

Capacitor provides the adjustMarginsForEdgeToEdge __CAPGO_KEEP_0__ には、この目的のために開発された設定オプションが用意されています。この設定オプションは、公式の __CAPGO_KEEP_0__ 設定ドキュメントに記載されています。 official Capacitor config documentation, ですが、簡単に逃すことができます。

設定方法

このように追加してください 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"
  }
}

設定オプション

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

1. `"auto"` 機能するようにする:

adjustMarginsForEdgeToEdge: 'auto'

Android 15+ と設定を自動で確認し、デバイスと設定に基づいて余白を適切に調整します。 設定オプション windowOptOutEdgeToEdgeEnforcement オプションは、3つの値を受け入れます:

最適: 主に、Android のバージョンに関係なく、エッジ・トゥ・エッジのレイアウトをサポートするデバイスで動作するアプリケーション向けです。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

機能: Android のバージョンやその他の設定に関係なく、エッジ・トゥ・エッジのレイアウトを強制します。

最適: すべてのサポートされている Android バージョンでエッジ・トゥ・エッジの動作を実現したいアプリケーション向けです。

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

機能: 自動マージン調整を完全に無効にします。

最適: エッジ・トゥ・エッジのレイアウトを手動で管理したい、またはエッジ・トゥ・エッジの動作を実現したくないアプリケーション向けです。

注意: 現在の状況 "disable" はデフォルトですが、この設定は__CAPGO_KEEP_0__ 8.に変更されます。 "auto" はCapacitor 8.に設定されます。

Android 15+の場合に何が重要か

Android 15以降、Googleはエッジツーヨエードディスプレイをデフォルトの動作として強制しています。エッジツーヨエードレイアウトを適切に処理していないアプリでは、次のようなUI問題が発生する可能性があります。

システムバーの後ろに隠れたコンテンツ
不適切なスペーシングとパディング
デバイス間で不一致な外観
不快なユーザー体験

公式の adjustMarginsForEdgeToEdge 設定を使用すると、カスタム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 Considerations

edge-to-edgeディスプレイを使用する場合、安全エリアを処理するための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";
}

Testing Your Configuration

設定を完了した後、以下のデバイスでアプリをテストしてください: adjustMarginsForEdgeToEdgeAndroid 15+デバイス

- システムバーに適切にコンテンツが対応していることを確認する 古いAndroidバージョン
- バックワードコンパチビリティを確保する 異なる画面サイズ
- デバイス間でレイアウトが正常に動作することを確認する ライトとダークのテーマ
__CAPGO_KEEP_0__ - テーマモードの両方をテストする

よくある間違いを避ける

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

あなたは第三者のプラグインのようなものが必要ない capacitor-edge-to-edge または類似のもの。ネイティブの設定はこの機能をきれいに処理します。ネイティブの設定を有効にした後、システムのブラウザの詳細な制御が必要な場合は adjustMarginsForEdgeToEdge, @capgo/capacitor-ナビゲーションバーそして @capgo/ホームインディケーターネイティブの設定を補完することなく置き換えるのではなく、ネイティブの設定と組み合わせてください。

マニュアル実装と組み合わせないでください

あなたが adjustMarginsForEdgeToEdge, を使用している場合、手動でウィンドウのインセットの処理やCSSのハックを削除してください。

__CAPGO_KEEP_0__

安全領域 CSS を忘れないで

__CAPGO_KEEP_1__

マイグレーションガイド

__CAPGO_KEEP_2__ 現在、エッジツーヨークラッカーやハックを使用している場合:
__CAPGO_KEEP_3__ エッジツーヨークラッカーやハックを削除する capacitor.config.ts
__CAPGO_KEEP_4__ から依存関係
__CAPGO_KEEP_5__ 設定オプションを追加する

# 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 を更新 安全なエリアを適切に処理するために
レイアウトを確認 エッジツーヨーロッジ機能が有効になっているデバイスで

追加リソース

結論

Capacitor のエッジツアー表示では、プラグイン、ハック、複雑なワークアラウンドが必要ありません。 Capacitor の設定オプションは、クリーンでネイティブの解決策を提供し、公式にサポートされており、将来に耐えるものです。 adjustMarginsForEdgeToEdge 大多数のアプリでは、__CAPGO_KEEP_0__ で始め、各種デバイスで徹底的にテストし、適切なセーフエリア CSS を追加してください。最小限の努力で、Android 15 以降に対応するアプリが完成します。

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

__CAPGO_KEEP_0__ のエッジツアー表示でプラグインなしで進めましょう The Capacitor community and 問題が発生している場合は? コミュニティ

Keep going from Edge-to-Edge Display in Capacitor Without Plugins

If you are using __CAPGO_KEEP_0__ Edge-to-Edge Display in Capacitor Without Plugins to plan native media and interface behavior, connect it with __CAPGO_KEEP_0__ Using @capgo/capacitor-live-activities for the native capability in Using @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 native capability in Using @capgo/capacitor-native-navigation.

Capacitorでエッジツーヘッジディスプレイを実現する