Randlos an die Ränder in Capacitor ohne Plugins

Versuchen Sie, eine randlose Anzeige in Ihrer Capacitor-Anwendung umzusetzen? Sie benötigen keine Hacks, Plugins oder Workarounds. Capacitor unterstützt die randlose Anzeige offiziell über die adjustMarginsForEdgeToEdge Einstellung - sie ist jedoch nicht weit verbreitet dokumentiert.

Viele Entwickler haben Schwierigkeiten mit randlosen Layouts in Capacitor-Anwendungen, insbesondere wenn sie sich auf Android 15+ richten. Sie greifen oft auf benutzerdefinierte Plugins oder CSS-Hacks zurück, um das moderne Aussehen einer randlosen Anzeige zu erreichen. Aber es gibt eine bessere, native Lösung.

Was ist eine randlose Anzeige?

Die randlose Anzeige ermöglicht es, dass sich das Inhalt Ihrer App hinter den Systemleisten (Statusleiste und Navigationsleiste) erstreckt, was eine umfassendere, moderne Benutzeroberfläche schafft. Ab Android 15 drängt Google die randlose Anzeige als Standard für alle Anwendungen vor.

Die offizielle Lösung: adjustMarginsForEdgeToEdge

Capacitor bietet die adjustMarginsForEdgeToEdge Konfigurationsoption speziell für diesen Zweck. Dies ist in der Capacitor-Konfigurationsdokumentationdokumentiert, aber es ist leicht zu übersehen.

Wie Sie es einrichten

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 nimmt drei Werte an:

1. `"auto"` (Empfohlen)

adjustMarginsForEdgeToEdge: 'auto'

Was es tut: Automatisch überprüft es Android 15+ und die Einstellung. Anpasset die Margen intelligent basierend auf dem Gerät und der Konfiguration. windowOptOutEdgeToEdgeEnforcement Am besten geeignet für:

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

Zwingt Anpassungen der Margen für Rand-zu-Rand unabhängig von der Android-Version oder anderen Einstellungen. Am besten geeignet für:

Anwendungen, die eine Rand-zu-Rand-Ansicht auf allen unterstützten Android-Versionen wollen. Was es tut:

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

Deaktiviert die automatischen Anpassungen der Margen vollständig. Am besten geeignet für:

Die meisten Produktionsanwendungen, die auf unterstützten Geräten eine Rand-zu-Rand-Ansicht wollen, während die Kompatibilität mit älteren Android-Versionen aufrechterhalten bleibt. Apps, die die Layoutbearbeitung von Anfang bis Ende selbstständig durchführen oder keine Anfang-bis-Ende-Bearbeitung wünschen.

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

Ab Android 15 erzwingt Google die Anfang-bis-Ende-Anzeige als Standardverhalten. Apps, die die Anfang-bis-Ende-Layouts nicht ordnungsgemäß bearbeiten, können UI-Probleme wie folgende erleben:

Inhalt versteckt hinter Systemleisten

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

Capgo adjustMarginsForEdgeToEdge Konfiguration, damit sichere Änderungen richtig behandelt werden, ohne eine benutzerdefinierte code.

Vollständiges Beispiel

Hier ist eine vollständige Beispielkonfiguration für eine moderne Capacitor-Anwendung:

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

Bei Verwendung einer edge-to-edge-Anzeige 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

Nach der Konfiguration adjustMarginsForEdgeToEdgetesten Sie Ihre App auf:

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

Häufige 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.

Mischen Sie nicht mit manuellen Implementierungen

Wenn Sie adjustMarginsForEdgeToEdgeentfernen Sie alle manuellen Fenster-Einrastungs-Handling oder CSS-Hacks, die Sie hinzugefügt haben.

Verpassen Sie nicht die Safe Area CSS

Die Konfiguration handhabt Anpassungen am Rand, aber Sie müssen immer noch CSS-sichere Bereiche für einen korrekten Inhalt einfügen.

Migrationsanleitung

Wenn Sie derzeit Plugins oder Hacks für randlos verwenden:

Entfernen Sie alle Plugins für randlos aus Ihren Abhängigkeiten
Fügen Sie die Konfigurationsoption zu Ihrem capacitor.config.ts
Reinigen und neu erstellen Ihren 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 android

Zukunftsweisende Vorbereitung

Denken Sie daran, dass Capacitor 8 den Standardwert setzen wird. "auto" Zur Vorbereitung:

Testen Sie mit "auto" jetzt um frühzeitig Probleme aufzuspüren
Aktualisieren Sie Ihre CSS um sicherzustellen, dass sich die sicheren Bereiche ordnungsgemäß verhalten
Überprüfen Sie Ihre Layouts auf Geräten mit aktivierter Edge-to-Edge-Funktion

Zusätzliche Ressourcen

Zusammenfassung

Ein Rand-zu-Rand-Bildschirm in Capacitor erfordert keine Plugins, Hacks oder komplizierte Workarounds. Die adjustMarginsForEdgeToEdge Konfigurationsoption bietet eine saubere, native Lösung, die offiziell unterstützt und zukunftssicher ist.

Mit "auto" für die meisten Apps, gründlich testen Sie über Geräte hinweg und fügen Sie die entsprechenden sicherheitsrelevanten 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? The Capacitor community and Community von __CAPGO_KEEP_0__ und offizielle Dokumentation

Edge-to-Edge Display in Capacitor ohne Plugins