エッジ・トゥ・エッジディスプレイのCapacitor

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

Capacitorでエッジツーヨークディスプレイを適切に設定する方法を学びましょう。公式のadjustMarginsForEdgeToEdge設定オプションを使用するだけで、プラグインやハックは必要ありません。

Article credits

マーティン・ドナディュー

ライター

バレリア

レビュアー

ジョーダン

エディター

プラグインやハックは必要ありません。Capacitorはエッジツーヨークディスプレイに対する公式のサポートを提供していますが、広く知られていない設定オプションがあります。 Capacitor adjustMarginsForEdgeToEdge __CAPGO_KEEP_0__

多くの開発者は、Capacitor アプリでエッジ・トゥ・エッジレイアウトに苦労しています、特にAndroid 15+をターゲットとしています。しばしば、カスタムプラグインやCSSハックを使用して、モダンなエッジ・トゥ・エッジの見た目を実現する必要があります。しかし、より良い、ネイティブの方法があります。

エッジ・トゥ・エッジ・ディスプレイとは何ですか。

エッジ・トゥ・エッジディスプレイは、システムバー（ステータスバーとナビゲーションバー）後ろにアプリのコンテンツを延長する機能です。これにより、よりインマーシブでモダンなUI体験が実現されます。 Android 15から、Googleはすべてのアプリでエッジ・トゥ・エッジを標準として推進しています。

オフィシャルソリューション: EdgeToEdge表示用のマージンを調整

Capacitorは adjustMarginsForEdgeToEdge この目的のために特に設計された official Capacitor config documentationの公式ドキュメント

に記載されていますが、見落としやすいことがあります。

How to Configure It capacitor.config.ts or 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;

または

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

設定オプション

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

1. `"auto"` (推奨)

adjustMarginsForEdgeToEdge: 'auto'

機能するようにすること: Android 15以上と設定を自動で確認し、 windowOptOutEdgeToEdgeEnforcement デバイスと設定に応じて、適切な余白を自動で調整します。

最適な状況: Android 15以上のサポートデバイスでエッジからエッジまで表示することを望む、互換性のある古いAndroidバージョンを維持したいアプリの多くに適しています。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

機能するようにすること: エッジからエッジまでの余白調整を、Androidバージョンや他の設定に関係なく強制します。

最適な状況: Android全バージョンでエッジツーヨークの動作を実現したいアプリ

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

Capacitor Edge to Edge Display Native Config には以下の機能があります。 自動マージン調整を完全に無効にする

ベスト・フォー： エッジツーヨークのレイアウトを手動で管理したり、エッジツーヨークの動作を実現したいアプリ

Note: 現在 "disable" はデフォルトですが、__CAPGO_KEEP_0__ 8では "auto" Capacitor 8.

Android 15 以降の意味

Android 15以降、Googleはエッジツーヨークの表示をデフォルトの動作として強制しています。エッジツーヨークのレイアウトを適切に管理していないアプリでは、次のような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 または類似のものは必要ありません。ネイティブ設定では、この機能をきれいに処理します。システムのブラウザの詳細な制御が必要な場合は、 adjustMarginsForEdgeToEdge, @capgo/capacitor-ナビゲーションバーと @capgo/ホームインジケーターネイティブ設定を補完するだけで置き換えることはありません。

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

あなたが使用している場合 adjustMarginsForEdgeToEdge手動でウィンドウのインセットの取り扱いまたはCSSのハックを削除してください。

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

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

移行ガイド

あなたが現在使用しているプラグインやエッジツーヨークスのハックがある場合

エッジツーヨークスのプラグインを削除してください 依存関係から
Capacitor Edge to Edge Display Native Config に対して設定オプションを追加します あなたの capacitor.config.ts
Android プロジェクトをクリーンアップし、再構築します ターゲットデバイスで徹底的にテストします
将来の対策 __CAPGO_KEEP_0__ 8 がデフォルト値になります。準備するには:

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

# Rebuild
npx cap copy android
npx cap open android

現在の

Capacitor "auto" __CAPGO_KEEP_0__

__CAPGO_KEEP_0__ "auto" now 早期に問題を検出するために
CSSを更新してください エッジデバイスで安全なエリアを適切に処理するために
レイアウトを確認してください エッジデバイスで有効になっている場合

追加のリソース

結論

エッジからエッジまでのディスプレイはCapacitorでプラグイン、ハック、複雑なワークアラウンドが必要なくても機能します。 adjustMarginsForEdgeToEdge __CAPGO_KEEP_0__でエッジデバイスをサポートするには、汚い、非公式なソリューションは必要ありません。

始めて "auto" 質問や問題が発生した場合は?

コミュニティと公式ドキュメントは、追加のヘルプのために素晴らしいリソースです。 Edge-to-EdgeディスプレイをCapacitorでプラグインなしで使用する Edge-to-Edgeディスプレイを__CAPGO_KEEP_0__でプラグインなしで使用する追加のヘルプは、以下のリソースで得られます。

エッジ・トゥ・エッジ・ディスプレイから続けてください。Capacitor にはプラグインを使用せずに

Edge-to-Edgeディスプレイを__CAPGO_KEEP_0__でプラグインなしで使用する場合、ネイティブ機能のために__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activitiesを使用します。 エッジ・トゥ・エッジ・ディスプレイをCapacitorでプラグインなしで実現 nativeメディアとインターフェイスの挙動を計画するには、接続する @capgo/capacitorライブアクティビティ Edge-to-Edgeディスプレイをcapgoでプラグインなしで使用する場合、ネイティブ機能のためにcapgo/capacitor-live-activitiesを使用します。 @capgo/capacitor-ライブアクティビティ @capgo/capacitor-ライブアクティビティの実装詳細について Using @capgo/capacitor-ビデオプレーヤー Using @capgo/capacitor-ビデオプレーヤーにおけるネイティブ機能 @capgo/capacitor-ビデオプレーヤー @capgo/capacitor-ビデオプレーヤーにおける実装詳細と Using @capgo/capacitor-ネイティブナビゲーション Using @capgo/capacitor-ネイティブナビゲーションにおけるネイティブ機能