Versuchen Sie, das Kantenlos-Display in Ihrer Capacitor-Anwendung umzusetzen? Sie benötigen keine Hacks, Plugins oder Workarounds. Capacitor unterstützt das Kantenlos-Display offiziell über die adjustMarginsForEdgeToEdge Konfigurationsoption - es ist einfach nicht weit verbreitet dokumentiert.
Viele Entwickler haben Schwierigkeiten mit edge-to-edge-Ansichten in Capacitor-Apps, insbesondere wenn sie sich auf Android 15+ richten. Sie greifen oft auf benutzerdefinierte Plugins oder CSS-Hacks zurück, um den modernen edge-to-edge-Look zu erreichen. Aber es gibt eine bessere, nativere Möglichkeit.
Was ist Edge-to-Edge Display?
Edge-to-Edge-Display ermöglicht es Ihrem App-Inhalt, hinter den Systemleisten (Statusleiste und Navigationsleiste) zu reichen, was eine umfassendere, moderne Benutzeroberfläche schafft. Ab Android 15 drängt Google edge-to-edge als Standard für alle Apps vor.
Die offizielle Lösung: adjustMarginsForEdgeToEdge
Capacitor bietet die adjustMarginsForEdgeToEdge Konfigurationsoption speziell für diesen Zweck an. Dies ist in der offiziellen Capacitor-Konfigurationsdokumentation erwähnt, aber es ist leicht zu übersehen.
Konfiguration
Fügen Sie dies 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;Oder in JSON-Format:
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}Konfigurationsoptionen
Die adjustMarginsForEdgeToEdge Option akzeptiert drei Werte:
1. "auto" (Empfohlen)
adjustMarginsForEdgeToEdge: 'auto'Was es tut: Automatisch überprüft es Android 15+ und die windowOptOutEdgeToEdgeEnforcement Einstellung. Anpassen Sie die Ränder intelligent basierend auf dem Gerät und der Konfiguration.
Am besten für: Die meisten Produktionsanwendungen, die eine Rand-zu-Rand-Anzeige auf unterstützten Geräten wollen, während die Kompatibilität mit älteren Android-Versionen aufrechterhalten wird.
2. "force"
adjustMarginsForEdgeToEdge: 'force'Was es tut: Zwingt Anpassungen der Ränder für Rand-zu-Rand, unabhängig von der Android-Version oder anderen Einstellungen.
Am besten geeignet für: Apps, die eine edge-to-edge-Behandlung auf allen unterstützten Android-Versionen anstreben.
3. "disable"
adjustMarginsForEdgeToEdge: 'disable'Was es tut: Automatische Randanpassungen komplett deaktiviert.
Am besten geeignet für: Apps, die die edge-to-edge-Anordnung manuell bearbeiten oder keine edge-to-edge-Behandlung wünschen.
Hinweis: Derzeit "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 edge-to-edge-Anzeige als Standardverhalten. Apps, die keine edge-to-edge-Anordnung ordnungsgemäß handhaben, können UI-Probleme wie:
Apps that don’t properly handle edge-to-edge layouts may experience UI issues like:
- Inhalt hinter Systemleisten versteckt
- Unangenehme Abstände und Pufferung
- Unkonsistente Erscheinung auf verschiedenen Geräten
- Schlechte Benutzererfahrung
Mit der offiziellen adjustMarginsForEdgeToEdge Konfiguration stellen Sie sicher, dass Ihre App diese Änderungen ordnungsgemäß handhabt, ohne eine benutzerdefinierte code.
Vollständiges Beispiel
Ein vollständiges Beispielkonfiguration 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-Betrachtungen
Wenn Sie eine edge-to-edge-Anzeige 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 die Konfiguration adjustMarginsForEdgeToEdge, test your app on:
- Android-Geräte ab Version 15 - Überprüfen Sie, ob der Inhalt die Systemleisten respektiert
- Ältere Android-Versionen - Stellen Sie sicher, dass die Anwendung auf älteren Versionen kompatibel ist
- Verschiedene Bildschirmgrößen - Überprüfen Sie, ob die Layouts auf verschiedenen Geräten funktionieren
- Helligkeit und Dunkelheit - Testen Sie beide Themenmodi
Häufige Fehler zu vermeiden
Verwenden Sie keine Plugins für diesen Zweck
Sie benötigen keine dritten Plugins wie capacitor-edge-to-edge oder ähnlich. Die native Konfiguration handhabt dies sauber. Wenn Sie eine feinmaschige Kontrolle über das System-Chrome benötigen, nachdem Sie es aktiviert haben adjustMarginsForEdgeToEdge, @capgo/capacitor-Navigationsleiste und @capgo/Startanzeige ergänzen Sie die native Konfiguration ohne sie zu ersetzen
Vermeiden Sie die Kombination mit manuellen Implementierungen
Wenn Sie adjustMarginsForEdgeToEdgeentfernen Sie alle manuellen Fenster-Einrastungen-Handling oder CSS-Hacks, die Sie hinzugefügt haben
Verpassen Sie nicht die Safe-Area-CSS
Die Konfiguration handhabt die Randjustierungen, aber Sie müssen immer noch die CSS-Safe-Area-Einrastungen verwenden, um einen korrekten Inhaltspuffer zu erhalten
Anleitung zur Migration
Wenn Sie derzeit Plugins oder Hacks für edge-to-edge verwenden
- Entfernen Sie alle Plugins mit Rand-zu-Rand aus Ihren Abhängigkeiten
- Fügen Sie die Konfigurationsoption hinzu zu Ihrem
capacitor.config.ts - Reinigen und neu erstellen Sie Ihr Android-Projekt
- Testen Sie gründlich auf Zielgeräten
# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..
# Rebuild
npx cap copy android
npx cap open androidZukunftsweisendes
Denken Sie daran, dass Capacitor 8 die Standardwerte setzen wird. Um sich auf die Zukunft vorzubereiten: "auto" Testen Sie mit
- Testen Sie auf Zielgeräten
"auto"jetzt um frühzeitig alle Probleme zu erkennen - aktualisieren Sie Ihre CSS um sichere Bereiche ordnungsgemäß zu behandeln
- Überprüfen Sie Ihre Layouts auf Geräten mit aktivierter Edge-to-Edge-Funktion
Zusätzliche Ressourcen
- Offizielles Capacitor Konfigurationsdokumentation
- Android-Richtlinien für Edge-to-Edge-Anwendungen
- CSS-Sichere Bereiche
Zusammenfassung
Edge-to-Edge-Anzeige in Capacitor erfordert keine Plugins, Hacks oder komplizierte Workarounds. Die adjustMarginsForEdgeToEdge Konfigurationsoption bietet eine saubere, native Lösung, die offiziell unterstützt und zukunftsweisend ist.
Mit "auto" Für die meisten Apps, testen Sie gründlich auf verschiedenen Geräten und fügen Sie die entsprechende Safe-Area-CSS hinzu. Ihre App ist mit minimalen Anstrengungen für Android 15 und darüber hinaus bereit.
Haben Sie Fragen oder stoßen Sie auf Probleme? Die Capacitor-Community und die offizielle Dokumentation sind großartige Ressourcen für zusätzliche Hilfe.
Fortsetzen Sie von 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-activities Für die native Fähigkeit in Verwendung von @capgo/capacitor-live-aktivitäten, @capgo/capacitor-live-aktivitäten Für die Implementierungsdetails in @capgo/capacitor-live-aktivitäten, Verwendung von @capgo/capacitor-video-player Für die native Fähigkeit in 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-navigations Für die native Fähigkeit in Verwendung von @capgo/capacitor-native-navigations.
