Willst du das Edge-to-Edge-Display in deiner Capacitor App implementieren? Du brauchst keine Hacks, Plugins oder Workarounds. Capacitor bietet offiziellen Support für Edge-to-Edge-Displays durch den adjustMarginsForEdgeToEdge Konfigurationsoption – sie ist einfach kaum dokumentiert.
Viele Entwickler haben Probleme mit Edge-to-Edge-Layouts in Capacitor-Apps, besonders bei Android 15+. Oft greifen sie auf Custom Plugins oder CSS-Hacks zurück, um den modernen Edge-to-Edge-Look zu erreichen. Aber es gibt einen besseren, nativen Weg.
Was ist Edge-to-Edge-Display?
Edge-to-Edge-Display lässt den App-Content hinter den Systemleisten (Status- und Navigationsleiste) verlaufen und sorgt so für ein immersiveres, modernes UI-Erlebnis. Ab Android 15 macht Google Edge-to-Edge zum Standard für alle Apps.
Die offizielle Lösung: adjustMarginsForEdgeToEdge
Capacitor bietet die adjustMarginsForEdgeToEdge Konfigurationsoption speziell für diesen Zweck. Dies ist in der offiziellen Capacitor Config-Dokumentationzu finden, wird aber leicht übersehen.
So konfigurierst du es
Füge dies zu deiner 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;Oder im JSON-Format:
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}Konfigurationsoptionen
Der adjustMarginsForEdgeToEdge Die Option akzeptiert drei Werte:
1. "auto" (Empfohlen)
adjustMarginsForEdgeToEdge: 'auto'Funktionsweise: Prüft automatisch auf Android 15+ und die windowOptOutEdgeToEdgeEnforcement Einstellung. Passt die Margins je nach Gerät und Konfiguration intelligent an.
Ideal für: Die meisten Produktions-Apps, die Edge-to-Edge auf unterstützten Geräten wollen und dabei mit älteren Android-Versionen kompatibel bleiben müssen.
2. "force"
adjustMarginsForEdgeToEdge: 'force'Funktionsweise: Erzwingt Margin-Anpassungen für Edge-to-Edge, unabhängig von der Android-Version oder anderen Einstellungen.
Ideal für: Apps, die ein Edge-to-Edge-Layout über alle Android-Versionen hinweg anstreben.
3. "disable"
adjustMarginsForEdgeToEdge: 'disable'Funktionsweise: Deaktiviert automatische Margin-Anpassungen vollständig.
Ideal für: Apps, die das Edge-to-Edge-Layout manuell steuern oder kein Edge-to-Edge wünschen.
Hinweis: Aktuell "disable" ist der Standard, dies wird sich jedoch zu "auto" in Capacitor 8 ändern.
Warum das für Android 15+ wichtig ist
Ab Android 15 erzwingt Google das Edge-to-Edge-Display als Standardverhalten. Apps, die Edge-to-Edge-Layouts nicht korrekt handhaben, könnten UI-Probleme bekommen, wie zum Beispiel:
- Inhalt wird von Systemleisten verdeckt
- Unpassende Abstände und Paddings
- Inkonsistentes Design auf verschiedenen Geräten
- Schlechte User Experience
Durch die Nutzung der offiziellen adjustMarginsForEdgeToEdge Config stellst du sicher, dass deine App diese Änderungen ohne eigene code korrekt verarbeitet.
Vollständiges Beispiel
Hier ist eine vollständige Beispiel-Konfiguration für eine moderne 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-Überlegungen
Bei der Nutzung von Edge-to-Edge-Displays musst du eventuell CSS für die Safe Areas hinzufügen:
/* 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";
}Konfiguration testen
Nach der Konfiguration adjustMarginsForEdgeToEdge, teste deine App auf:
- Android 15+ Geräte - Prüfe, dass der Content die System Bars korrekt respektiert
- Ältere Android-Versionen - Stelle die Abwärtskompatibilität sicher
- Verschiedene Bildschirmgrößen - Layouts auf verschiedenen Geräten prüfen
- Light- und Dark-Themes - Teste beide Theme-Modi
Häufige Fehler, die du vermeiden solltest
Nutze keine Plugins dafür
Du brauchst keine Third-Party-Plugins wie capacitor-edge-to-edge oder Ähnliches. Die Native Config regelt das sauber. Falls du nach der Aktivierung eine feingranulare Kontrolle über das System Chrome benötigst, adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar und @capgo/home-indicator ergänzen die native Config, ohne sie zu ersetzen.
Nicht mit manuellen Implementierungen mischen
If you’re using adjustMarginsForEdgeToEdgeentferne alle manuellen Window-Insets-Handlings oder CSS-Hacks, die du eventuell hinzugefügt hast.
Safe Area CSS nicht vergessen
Die Config regelt die Margin-Anpassungen, aber du musst weiterhin CSS Safe Area Insets für das richtige Content-Padding nutzen.
Migrationsguide
Wenn du aktuell Plugins oder Hacks für Edge-to-Edge nutzt:
- Entferne alle Edge-to-Edge-Plugins aus deinen Abhängigkeiten
- Füge die Config-Option hinzu in deine
capacitor.config.ts - Clean und rebuild dein Android-Projekt
- Gründlich testen auf den Zielgeräten
# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..
# Rebuild
npx cap copy android
npx cap open androidZukunftssicherheit
Denk daran, dass Capacitor 8 "auto" zum Standardwert macht. Zur Vorbereitung:
- Testen mit
"auto"jetzt um Probleme frühzeitig zu erkennen - CSS aktualisieren um Safe Areas korrekt zu handhaben
- Layouts prüfen auf Geräten mit Edge-to-Edge-Display
Weitere Ressourcen
Fazit
Edge-to-Edge-Displays in Capacitor benötigen keine Plugins, Hacks oder komplizierte Workarounds. Das adjustMarginsForEdgeToEdge Diese Konfigurationsoption bietet eine saubere, native Lösung, die offiziell unterstützt und zukunftssicher ist.
Starte mit "auto" Testen Sie die meisten Apps gründlich auf verschiedenen Geräten und fügen Sie passendes Safe-Area-CSS hinzu. So ist Ihre App mit minimalem Aufwand bereit für Android 15 und darüber hinaus.
Questions or running into issues? Die Capacitor Community und offiziellen Dokumentation sind großartige Ressourcen für weitere Hilfe.
Weiterlesen: Edge-to-Edge Display in Capacitor ohne Plugins
Wenn du es nutzt Edge-to-Edge-Display in Capacitor ohne Plugins , um natives Media- und Interface-Verhalten zu planen, verbinde es mit @capgo/capacitor-live-activities verwenden für die native Funktion in „@capgo/capacitor-live-activities verwenden“, @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities, Verwendung von @capgo/capacitor-video-player für die native Funktion bei Verwendung von @capgo/capacitor-video-player, @capgo/capacitor-video-player für die Implementierungsdetails in @capgo/capacitor-video-player und Verwendung von @capgo/capacitor-native-navigation für die native Funktion bei Verwendung von @capgo/capacitor-native-navigation.
