Fenstereinbauten

Die Android-Plattform ist für das Rendern der System-UI verantwortlich, z. B. der Statusleiste und der Navigationsleiste. Diese System-UI wird unabhängig davon angezeigt, welche App der Nutzer verwendet.

WindowInsets enthält Informationen zur System-UI, damit Ihre App im richtigen Bereich gerendert wird und die UI nicht durch die System-UI verdeckt wird.

Abbildung 1. Inhalte werden über den gesamten Bildschirmrand hinaus hinter den Systemleisten angezeigt.

Unter Android 14 (API-Level 34) und niedriger wird die Benutzeroberfläche Ihrer App standardmäßig nicht unter den Systemleisten und Display-Ausschnitten gerendert.

Unter Android 15 (API‑Level 35) und höher wird Ihre App unter den Systemleisten und Displayausschnitten gerendert, sobald sie auf SDK 35 ausgerichtet ist. Das führt zu einer nahtloseren Nutzererfahrung und ermöglicht es Ihrer App, den ihr zur Verfügung stehenden Fensterbereich optimal zu nutzen.

Wenn Inhalte hinter der System-UI angezeigt werden, wird dies als Edge-to-Edge-Anzeige bezeichnet. Auf dieser Seite erfahren Sie mehr über die verschiedenen Arten von Insets, wie Sie den Edge-to-Edge-Modus verwenden und wie Sie die Inset-APIs verwenden, um die Benutzeroberfläche zu animieren und dafür zu sorgen, dass die Inhalte Ihrer App nicht durch System-UI-Elemente verdeckt werden.

Wichtig :Die randlose Darstellung wird ab Android 15 erzwungen, sobald Ihre App auf SDK 35 ausgerichtet ist. Wenn Ihre App noch nicht randlos ist, werden möglicherweise Teile der App ausgeblendet. In diesem Fall müssen Sie Insets berücksichtigen. Je nach App kann dieser Aufwand erheblich sein. Die Material 3-Komponente Scaffold kann den Aufwand für die Kompatibilität mit der Android 15-Richtlinie für Edge-to-Edge-Apps reduzieren. Weitere Informationen finden Sie unter Scaffold-Komponente erstellen, um die Benutzeroberfläche zusammenzuhalten.

Grundlagen für Insets

Wenn eine App über den gesamten Bildschirmrand hinausgeht, müssen Sie dafür sorgen, dass wichtige Inhalte und Interaktionen nicht durch die System-UI verdeckt werden. Wenn sich eine Schaltfläche beispielsweise hinter der Navigationsleiste befindet, kann der Nutzer möglicherweise nicht darauf klicken.

Die Größe der System-UI und Informationen dazu, wo sie platziert wird, werden mit Insets angegeben.

Jeder Teil der System-UI hat einen entsprechenden Typ von Inset, der seine Größe und Position beschreibt. Statusleisten-Insets geben beispielsweise die Größe und Position der Statusleiste an, während Navigationsleisten-Insets die Größe und Position der Navigationsleiste angeben. Jeder Typ von Inset besteht aus vier Pixeldimensionen: oben, links, rechts und unten. Diese Dimensionen geben an, wie weit sich die System-UI von den entsprechenden Seiten des App-Fensters erstreckt. Um Überschneidungen mit dieser Art von System-UI zu vermeiden, muss die App-UI um diesen Betrag eingerückt werden.

Diese integrierten Android-Inset-Typen sind über WindowInsets verfügbar:

WindowInsets.statusBars	Die Insets, die die Statusleisten beschreiben. Dies sind die oberen System-UI-Leisten, die Benachrichtigungssymbole und andere Anzeigen enthalten.
WindowInsets.statusBarsIgnoringVisibility	Die Statusleisten-Insets, wenn sie sichtbar sind. Wenn die Statusleisten ausgeblendet sind (weil der immersive Vollbildmodus aktiviert wurde), sind die Insets der Hauptstatusleiste leer, aber diese Insets sind nicht leer.
WindowInsets.navigationBars	Die Insets, die die Navigationsleisten beschreiben. Das sind die System-UI-Leisten auf der linken, rechten oder unteren Seite des Geräts, die die Taskleiste oder Navigationssymbole beschreiben. Diese können sich zur Laufzeit ändern, je nachdem, welche Navigationsmethode der Nutzer bevorzugt und wie er mit der Taskleiste interagiert.
WindowInsets.navigationBarsIgnoringVisibility	Die Insets für die Navigationsleiste, wenn sie sichtbar ist. Wenn die Navigationsleisten ausgeblendet sind (weil der immersive Vollbildmodus aktiviert ist), sind die Insets der Hauptnavigationsleiste leer, aber diese Insets sind nicht leer.
WindowInsets.captionBar	Der Inset, der die Fensterdekoration der System-UI beschreibt, wenn sie sich in einem Freiformfenster befindet, z. B. die obere Titelleiste.
WindowInsets.captionBarIgnoringVisibility	Die Einzüge für die Untertitel-Leiste, wenn sie sichtbar ist. Wenn die Untertitelbalken ausgeblendet sind, sind die Insets des Hauptuntertitelbalkens leer, aber diese Insets sind nicht leer.
WindowInsets.systemBars	Die Vereinigung der Systemleisten-Insets, zu denen die Statusleisten, Navigationsleisten und die Untertitelzeile gehören.
WindowInsets.systemBarsIgnoringVisibility	Die Systemleisten-Insets, wenn sie sichtbar sind. Wenn die Systemleisten ausgeblendet sind (weil der immersive Vollbildmodus aktiviert wurde), sind die Insets der Hauptsystemleiste leer.
WindowInsets.ime	Die Insets, die den Platz unten beschreiben, den die Softwaretastatur einnimmt.
WindowInsets.imeAnimationSource	Die Insets, die den Platz beschreiben, den die Softwaretastatur vor der aktuellen Tastaturanimation eingenommen hat.
WindowInsets.imeAnimationTarget	Die Insets beschreiben den Platz, den die Softwaretastatur nach der aktuellen Tastaturanimation einnimmt.
WindowInsets.tappableElement	Eine Art von Insets, die detailliertere Informationen zur Navigations-UI enthalten. Sie geben an, wie viel Platz für „Taps“ vom System und nicht von der App reserviert wird. Bei transparenten Navigationsleisten mit Bedienung über Gesten können einige App-Elemente über die Systemnavigations-UI angetippt werden.
WindowInsets.tappableElementIgnoringVisibility	Die Insets für das tappbare Element, wenn es sichtbar ist. Wenn die tippable Elemente ausgeblendet sind (weil der immersive Vollbildmodus aktiviert ist), sind die Insets des wichtigsten tippable Elements leer.
WindowInsets.systemGestures	Die Insets, die die Anzahl der Insets darstellen, in denen das System Gesten für die Navigation abfängt. Apps können die Verarbeitung einer begrenzten Anzahl dieser Gesten mit Modifier.systemGestureExclusion manuell angeben.
WindowInsets.mandatorySystemGestures	Eine Teilmenge der Systemgesten, die immer vom System verarbeitet werden und die nicht mit Modifier.systemGestureExclusion deaktiviert werden können.
WindowInsets.displayCutout	Die Insets, die den Abstand angeben, der erforderlich ist, um eine Überlappung mit einer Display-Aussparung (Notch oder Pinhole) zu vermeiden.
WindowInsets.waterfall	Die Insets, die die gekrümmten Bereiche einer Wasserfallanzeige darstellen. Ein Waterfall-Display hat an den Rändern des Displays gebogene Bereiche, an denen sich das Display um die Seiten des Geräts wickelt.

Diese Typen werden durch drei „sichere“ Inset-Typen zusammengefasst, die dafür sorgen, dass Inhalte nicht verdeckt werden:

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

Diese „sicheren“ Inset-Typen schützen Inhalte auf unterschiedliche Weise, basierend auf den zugrunde liegenden Plattform-Insets:

• Verwenden Sie WindowInsets.safeDrawing, um Inhalte zu schützen, die nicht unter der System-UI gezeichnet werden sollen. Dies ist der häufigste Anwendungsfall für Insets: Sie verhindern, dass Inhalte gezeichnet werden, die von der System-UI verdeckt werden (entweder teilweise oder vollständig).
• Mit WindowInsets.safeGestures können Sie Inhalte mit Gesten schützen. So wird verhindert, dass Systemgesten mit App-Gesten (z. B. für Bottom Sheets, Karussells oder in Spielen) in Konflikt geraten.
• Verwenden Sie WindowInsets.safeContent als Kombination aus WindowInsets.safeDrawing und WindowInsets.safeGestures, um sicherzustellen, dass es keine visuellen oder gestischen Überschneidungen gibt.