Display-Aussparungen unterstützen

Compose ausprobieren
Jetpack Compose ist das empfohlene UI-Toolkit für Android. Informationen zum Arbeiten mit Displayausschnitten in Compose
Displayausschnitte in Compose →

Eine Display-Aussparung ist ein Bereich auf einigen Geräten, der in die Displayoberfläche hineinragt. So wird ein randloses Display ermöglicht und gleichzeitig Platz für wichtige Sensoren auf der Vorderseite des Geräts geschaffen.

Android unterstützt Display-Aussparungen auf Geräten mit Android 9 (API-Level 28) und höher. Gerätehersteller können jedoch auch Display-Aussparungen auf Geräten mit Android 8.1 oder niedriger unterstützen.

In diesem Dokument wird beschrieben, wie Sie vorgehen, damit Ihre App Geräte mit Aussparungen unterstützt. Dabei wird auf den richtigen Umgang mit dem Aussparungsbereich, d. h. dem randlosen Rechteck auf der Displayoberfläche, das die Aussparung enthält, eingegangen.

Bild mit einem Beispiel für eine mittig oben auf dem Display platzierte Display-Aussparung
Abbildung 1. 1 Display-Aussparung

Auswählen, wie Ihre App Ausschnittbereiche behandelt

Wenn Sie nicht möchten, dass sich Ihre Inhalte mit einem Ausschnittbereich überschneiden, reicht es in der Regel aus, darauf zu achten, dass sie sich nicht mit der Statusleiste und der Navigationsleiste überschneiden. Wenn Sie im Ausschnittbereich rendern, verwenden Sie WindowInsetsCompat.getDisplayCutout(), um ein DisplayCutout-Objekt abzurufen, das die sicheren Insets und den Begrenzungsrahmen für jeden Ausschnitt enthält. Mit diesen APIs können Sie prüfen, ob sich Ihre Inhalte mit dem Ausschnitt überschneiden, und sie bei Bedarf neu positionieren.

Sie können auch festlegen, ob Inhalte hinter dem Ausschnittbereich angeordnet werden sollen. Mit dem Attribut für das layoutInDisplayCutoutMode-Fensterlayout wird gesteuert, wie Ihre Inhalte im Ausschnittbereich dargestellt werden. Sie können layoutInDisplayCutoutMode auf einen der folgenden Werte festlegen:

  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: Inhalte werden im Ausschnittbereich gerendert, wenn sich die Display-Aussparung in einer Systemleiste befindet. Andernfalls überlappt das Fenster nicht die Display-Aussparung. Inhalte können beispielsweise im Querformat letterboxed dargestellt werden. Wenn Ihre App auf SDK 35 ausgerichtet ist, wird dies für nicht schwebende Fenster als ALWAYS interpretiert.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS: Inhalte dürfen sich immer in die Ausschnittbereiche erstrecken. Wenn Ihre App auf SDK 35 ausgerichtet ist und auf einem Android 15-Gerät ausgeführt wird, ist dies der einzige zulässige Modus für nicht schwebende Fenster, um eine randlose Anzeige zu gewährleisten.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: Inhalte werden sowohl im Hoch- als auch im Querformat im Bereich der Aussparung gerendert. Nicht für unverankerte Fenster verwenden. Wenn Ihre App auf SDK 35 ausgerichtet ist, wird dies für nicht schwebende Fenster als ALWAYS interpretiert.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: Inhalte werden nie im Ausschnittbereich gerendert. Wenn Ihre App auf SDK 35 ausgerichtet ist, wird dies für nicht schwebende Fenster als ALWAYS interpretiert.

Sie können den Ausschnittmodus entweder programmatisch oder durch Festlegen eines Stils in Ihrer Aktivität festlegen. Im folgenden Beispiel wird ein Stil definiert, mit dem das Attribut LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES auf die Aktivität angewendet wird.

<style name="ActivityTheme">
  <item name="android:windowLayoutInDisplayCutoutMode">
    shortEdges <!-- default, shortEdges, or never -->
  </item>
</style>

In den folgenden Abschnitten werden die verschiedenen Ausschnittmodi genauer beschrieben.

Standardverhalten

Wenn Ihre App auf SDK 35 ausgerichtet ist und auf einem Android 15-Gerät ausgeführt wird, ist LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS das Standardverhalten und LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT wird für nicht schwebende Fenster als LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS interpretiert.

Andernfalls ist LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT die Standardeinstellung.

Inhalte in Aussparungsbereichen an der kurzen Seite rendern

Wenn Ihre App auf SDK 35 ausgerichtet ist und auf einem Android 15-Gerät ausgeführt wird, wird LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES für nicht schwebende Fenster als LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS interpretiert.

Mit LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES erstreckt sich der Inhalt sowohl im Hoch- als auch im Querformat in den Ausschnittbereich an der kurzen Kante des Displays, unabhängig davon, ob die Systemleisten ausgeblendet oder sichtbar sind. Achten Sie bei der Verwendung dieses Modus darauf, dass keine wichtigen Inhalte mit dem Ausschnittbereich überlappen.

Das folgende Bild ist ein Beispiel für LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES auf einem Gerät im Hochformat:

Ein Bild, das zeigt, wie Inhalte im Hochformat im Bereich der Aussparung gerendert werden
Abbildung 2. Inhalte werden im Hochformat in den Bereich der Aussparung gerendert.

Das folgende Bild zeigt ein Beispiel für LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES auf einem Gerät im Querformat:

Ein Bild, auf dem zu sehen ist, wie Inhalte im Querformat im Bereich der Aussparung gerendert werden
Abbildung 3. Inhalte werden im Querformat im Bereich der Aussparung gerendert.

In diesem Modus erstreckt sich das Fenster sowohl im Hoch- als auch im Querformat unter die Ausschnitte an der kurzen Kante des Displays, unabhängig davon, ob das Fenster die Systemleisten verdeckt.

Ein Ausschnitt in der Ecke gilt als auf der kurzen Kante:

Bild eines Geräts mit einem Ausschnitt in der Ecke
Abbildung 4. Ein Gerät mit einem Ausschnitt in der Ecke

Inhalte niemals im Bereich der Display-Aussparung rendern

Wenn Ihre App auf SDK 35 ausgerichtet ist und auf einem Android 15-Gerät ausgeführt wird, wird LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER für nicht schwebende Fenster als LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS interpretiert.

Bei LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER darf sich das Fenster nie mit dem Ausschnittbereich überschneiden.

Das folgende Beispiel zeigt LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER im Hochformat:

Ein Bild, das LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER für das Hochformat zeigt
Abbildung 5: Beispiel für LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER im Porträtmodus.

Das folgende Beispiel zeigt LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER im Querformat:

Ein Bild, das LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER für das Querformat zeigt
Abbildung 6: Beispiel für LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER im Querformat.

Best Practices für die Unterstützung von Display-Aussparungen

Beachten Sie bei der Arbeit mit Displayausschnitten Folgendes:

  • Achten Sie auf die Platzierung wichtiger Elemente der Benutzeroberfläche. Der Aussparungsbereich darf keine wichtigen Texte, Steuerelemente oder andere Informationen verdecken.
  • Platzieren oder erweitern Sie keine interaktiven Elemente, die eine genaue Berührungserkennung erfordern, in den Aussparungsbereich. Die Berührungsempfindlichkeit ist im Bereich des Ausschnitts möglicherweise geringer.

  • Verwenden Sie nach Möglichkeit WindowInsetsCompat, um die Höhe der Statusleiste abzurufen und das entsprechende Padding für Ihre Inhalte zu bestimmen. Vermeiden Sie es, die Höhe der Statusleiste fest zu codieren, da dies zu überlappenden oder abgeschnittenen Inhalten führen kann.

    Ein Bild, auf dem Inhalte oben abgeschnitten sind, weil die Insets nicht richtig eingerichtet wurden
    Abbildung 7. Verwenden Sie WindowInsetsCompat, um Überschneidungen oder das Abschneiden von Inhalten zu vermeiden.

  • Mit View.getLocationInWindow() lässt sich ermitteln, wie viel Fensterplatz Ihre App verwendet. Gehen Sie nicht davon aus, dass die App das gesamte Fenster verwendet, und verwenden Sie nicht View.getLocationOnScreen().

  • Verwenden Sie die Ausschnittmodi always, shortEdges oder never, wenn Ihre App in den immersiven Modus wechseln und ihn wieder verlassen muss. Das Standardverhalten für den Ausschnitt kann dazu führen, dass Inhalte in Ihrer App im Ausschnittbereich gerendert werden, wenn die Systemleisten vorhanden sind, aber nicht im Immersive-Modus. Dadurch bewegen sich die Inhalte während der Übergänge nach oben und unten, wie im folgenden Beispiel gezeigt.

    Ein Bild, das zeigt, wie sich Inhalte bei Übergängen nach oben und unten bewegen.
    Abbildung 8: Beispiel für Inhalte, die sich während Übergängen nach oben und unten bewegen.

  • Achten Sie im immersiven Modus darauf, ob Sie Fenster- oder Bildschirmkoordinaten verwenden, da Ihre App bei einem Letterbox-Effekt nicht den gesamten Bildschirm nutzt. Aufgrund des Letterbox-Formats sind die Koordinaten vom Bildschirmursprung nicht dieselben wie die Koordinaten vom Fensterursprung. Mit getLocationOnScreen() können Sie Bildschirmkoordinaten nach Bedarf in die Koordinaten der Ansicht umwandeln. Das folgende Bild zeigt, wie sich die Koordinaten unterscheiden, wenn Inhalte letterboxed werden:

    Ein Bild, das Fenster- und Bildschirmkoordinaten zeigt, wenn Inhalte im Letterbox-Format dargestellt werden.
    Abbildung 9: Fenster- im Vergleich zu Bildschirmkoordinaten, wenn Inhalte im Letterbox-Format dargestellt werden.

  • Verwenden Sie beim Verarbeiten von MotionEvent die Funktionen MotionEvent.getX() und MotionEvent.getY(), um ähnliche Koordinatenprobleme zu vermeiden. Verwenden Sie nicht MotionEvent.getRawX() oder MotionEvent.getRawY().

Wiedergabe von Inhalten testen

Testen Sie alle Bildschirme und Funktionen Ihrer App. Testen Sie nach Möglichkeit auf Geräten mit verschiedenen Arten von Ausschnitten. Wenn Sie kein Gerät mit einem Ausschnitt haben, können Sie gängige Ausschnittkonfigurationen auf jedem Gerät oder Emulator mit Android 9 oder höher simulieren. Gehen Sie dazu so vor:

  1. Aktivieren Sie die Entwickleroptionen.
  2. Scrollen Sie auf dem Bildschirm Entwickleroptionen nach unten zum Bereich Zeichnen und wählen Sie Display mit Aussparung simulieren aus.

  3. Wählen Sie den Ausschnitttyp aus.

    Ein Bild, das zeigt, wie eine Display-Aussparung im Emulator simuliert wird
    Abbildung 10. Entwickleroptionen zum Testen der Darstellung Ihrer Inhalte.

Zusätzliche Ressourcen