Edge-to-Edge Display in Capacitor Without Plugins

Trying to implement edge-to-edge display in your Capacitor app? You don’t need any hacks, plugins, or workarounds. Capacitor has official support for edge-to-edge display through the adjustMarginsForEdgeToEdge Konfigurationsoption - sie ist jedoch nicht weit verbreitet dokumentiert.

Many developers struggle with edge-to-edge layouts in Capacitor apps, especially when targeting Android 15+. They often resort to custom plugins or CSS hacks to achieve the modern edge-to-edge look. But there’s a better, native way.

Was ist Kantenlos-Display?

Ein Kantenlos-Display ermöglicht es Ihrem App-Inhalt, hinter den Systemleisten (Statusleiste und Navigationsleiste) zu reichen, was eine umfassendere, moderne Benutzeroberfläche bietet. Ab Android 15 drängt Google Kantenlos als Standard für alle Apps vor.

Die offizielle Lösung: adjustMarginsForEdgeToEdge

Capacitor provides the adjustMarginsForEdgeToEdge Konfigurationsoption speziell für diesen Zweck. Dies ist in der offiziellen Capacitor Konfigurationsdokumentation, aber es ist leicht zu übersehen.

Wie Sie es einrichten

Hinzufügen Sie dies zu Ihrem capacitor.config.ts oder 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;

Konfigurationsoptionen

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

Die

Option akzeptiert drei Werte: adjustMarginsForEdgeToEdge (Empfohlen)

1. "auto" Was es tut:

adjustMarginsForEdgeToEdge: 'auto'

Konfigurationsoptionen Automatisch überprüft Android 15+ und das windowOptOutEdgeToEdgeEnforcement Die Einstellung anpasst die Ränder intelligent auf Basis des Geräts und der Konfiguration.

Am besten geeignet für: Die meisten Produktionsanwendungen, die eine Randlosigkeit auf unterstützten Geräten wollen, während die Kompatibilität mit älteren Android-Versionen aufrechterhalten bleibt.

2. "force"

adjustMarginsForEdgeToEdge: 'force'

Was es tut: Zwingt die Anpassung der Ränder für Randlosigkeit ungeachtet der Android-Version oder anderer Einstellungen.

Am besten geeignet für: Anwendungen, die eine Randlosigkeit über alle unterstützten Android-Versionen hinweg wollen.

3. "disable"

adjustMarginsForEdgeToEdge: 'disable'

Was es tut: Deaktiviert die automatische Anpassung der Ränder vollständig.

Am besten geeignet für: Anwendungen, die die Randlosigkeit Layout manuell handhaben oder keine Randlosigkeit wollen.

Hinweis: Aktuell "disable" ist die Standard-Einstellung, aber dies wird sich in __CAPGO_KEEP_0__ 8 ändern. "auto" in Capacitor 8.

Ab Android 15 erzwingt Google die Standard-Einstellung für Edge-to-Edge-Anzeigen. Apps, die diese Anzeigen nicht richtig handhaben, können UI-Probleme wie folgende erleben:

Inhalt, der hinter den Systemleisten verborgen ist

• Unangenehme Abstände und Paddings
• Unkonsistente Erscheinung auf verschiedenen Geräten
• Schlechte Benutzererfahrung
• Durch die Verwendung der offiziellen

Konfiguration stellen Sie sicher, dass Ihre App diese Änderungen richtig handhabt, ohne eine benutzerdefinierte __CAPGO_KEEP_0__. adjustMarginsForEdgeToEdge config, you ensure your app handles these changes properly without custom code.

Vollständiges Beispiel

Here’s a complete example configuration for a modern Capacitor app:

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-Betrachtungen

Wenn Sie einen Randlos-Display verwenden, müssen Sie möglicherweise einige CSS-Regeln hinzufügen, um sichere Bereiche zu handhaben:

/* 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";
}

Testen Sie Ihre Konfiguration

Nachdem Sie Ihre App konfiguriert haben, adjustMarginsForEdgeToEdgetesten Sie Ihre App auf:

1. Android-Geräte ab Version 15 - Überprüfen Sie, ob der Inhalt die Systemleisten korrekt respektiert
2. Ältere Android-Versionen - Stellen Sie sicher, dass die App kompatibel mit älteren Versionen ist
3. Verschiedene Bildschirmgrößen - Überprüfen Sie, ob die Layouts auf verschiedenen Geräten funktionieren
4. - Licht- und Dunkelthemen - Testen Sie beide Themenmodi

- Gemeinsame Fehler zu vermeiden

- Verwenden Sie keine Plugins für dies

- Sie benötigen keine dritten Parteien-Plugins wie capacitor-edge-to-edge - oder ähnliche. Die native Konfiguration handhabt dies sauber. Wenn Sie eine fein abgestimmte Kontrolle über das System-Chrome benötigen, nachdem Sie adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar - und @capgo/home-indicator -Home-Indikator

- ergänzen Sie die native Konfiguration, ohne sie zu ersetzen.

If Sie Edge-to-Edge-Displays verwenden adjustMarginsForEdgeToEdgeEntfernen Sie alle manuellen Fenster-Einrast-Handling oder CSS-Hacks, die Sie möglicherweise hinzugefügt haben.

Denken Sie an sichere Bereiche in CSS

Die Konfiguration handhabt Randanpassungen, aber Sie müssen immer noch CSS-sichere Bereiche für eine korrekte Inhaltsabstände verwenden.

Anleitung zur Migration

Wenn Sie derzeit Plugins oder Hacks für Edge-to-Edge verwenden:

1. Entfernen Sie alle Edge-to-Edge-Plugins aus Ihren Abhängigkeiten
2. Fügen Sie die Konfigurationsoption zu Ihrem capacitor.config.ts
3. Stellen Sie Ihr Android-Projekt sauber und neu zusammen. Entfernen Sie alle Plugins für Edge-to-Edge
4. Gründlich testen auf Zielgeräten

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

# Rebuild
npx cap copy android
npx cap open android

Zukunftssicherheit

Beachten Sie, dass Capacitor 8 die Standardwerte setzen wird. Um sich darauf vorzubereiten: "auto" Testen Sie mit

1. jetzt "auto" um frühzeitig Probleme zu erkennen Passen Sie Ihre CSS-Anweisungen an
2. um sichere Bereiche ordnungsgemäß zu behandeln Überprüfen Sie Ihre Layouts
3. auf Geräten mit aktivierter Randlos-Anzeige Testen Sie gründlich

Zusätzliche Ressourcen

• Offizielle Capacitor Konfigurationsdokumentation
• Android-Richtlinien für Edge-to-Edge-Anzeigen
• CSS-Sichere Bereiche für Ecken

Fazit

Edge-to-Edge-Anzeigen in Capacitor erfordern keine Plugins, Hacks oder komplizierte Workarounds. Die adjustMarginsForEdgeToEdge Konfigurationsoption bietet eine saubere, native Lösung, die offiziell unterstützt und zukunftssicher ist.

Beginnen Sie mit "auto" Für die meisten Apps, testen Sie gründlich auf verschiedenen Geräten und fügen Sie die entsprechenden Sicherheitsbereiche für Ecken in Ihrem CSS hinzu. Ihre App ist für Android 15 und darüber hinaus mit minimalen Anstrengungen bereit.

Fragen oder Probleme? Die Capacitor-Community und offizielle Dokumentation sind großartige Ressourcen für zusätzliche Hilfe.

Fortsetzen Sie mit Edge-to-Edge Display in Capacitor ohne Plugins.

Wenn Sie Edge-to-Edge Display in Capacitor ohne Plugins verwenden um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit Mit @capgo/capacitor-live-Aktivitäten für die native Fähigkeit in Mit @capgo/capacitor-live-Aktivitäten, @capgo/capacitor-live-Aktivitäten für die Implementierungsdetails in @capgo/capacitor-live-Aktivitäten, Mit @capgo/capacitor-Video-Player für die native Fähigkeit in Mit @capgo/capacitor-Video-Player, @capgo/capacitor-Video-Player Für die Implementierungsdetails in @capgo/capacitor-Video-Player und Mit @capgo/capacitor-Native-Navigation Für die native Fähigkeit in Mit @capgo/capacitor-Native-Navigation.