Ausschnitte in Compose

Auf einigen Geräten ist eine Display-Aussparung ein Bereich, der in die Displayoberfläche hinausgeht. Es ermöglicht eine randlose Bedienung und bietet Platz für wichtige Sensoren an der Vorderseite des Geräts.

Beispiel für einen Ausschnitt im Hochformat
Abbildung 1: Beispiel für einen Ausschnitt im Porträtmodus
Beispiel für einen Ausschnitt im Querformat
Abbildung 2: Beispiel für einen Ausschnitt im Querformat

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.

Auf dieser Seite wird beschrieben, wie Sie die Unterstützung für Geräte mit Aussparungen in Composer implementieren und mit dem Ausschnittbereich arbeiten, d. h. mit dem randlosen Rechteck auf der Displayoberfläche, das die Aussparung enthält.

Standard-Groß-/Kleinschreibung

Standardmäßig sind Display-Aussparungen in den Fenstereinfügungen enthalten. Aus diesem Grund zeichnet deine App nicht die Display-Aussparungen, wenn du der Anleitung zum randvollen Gestalten der App folgst.

Wenn Sie beispielsweise Modifier.windowInsetsPadding(WindowInsets.safeContent) oder Modifier.windowInsetsPadding(WindowInsets.safeDrawing) verwenden, zeichnet Ihre App automatisch nicht die Bereiche, in denen ein Ausschnitt platziert ist. WindowInsets.safeContent und WindowInsets.safeDrawing enthalten beide Informationen zum Displayausschnitt und werden nicht an der Stelle gezeichnet, an der sich eine Geräteaussparung befindet.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    WindowCompat.setDecorFitsSystemWindows(window, false)

    setContent {
        Box(Modifier.windowInsetsPadding(WindowInsets.safeContent)) {
            // Any composable inside here will avoid drawing behind cutouts
        }
    }
}
CutoutSnippets.kt

Um dieses Verhalten weiter anzupassen, müssen Sie die Aussparungsinformationen selbst verarbeiten.

Informationen zu Ausschnitten manuell verarbeiten

Für den Umgang mit Aussparungen gibt es folgende Möglichkeiten:

Es wird empfohlen, windowLayoutInDisplayCutoutMode im Gesamtdesign auf default zu setzen und dann WindowInsets.displayCutout zu verwenden, um die Einfügungen in Ihren zusammensetzbaren Funktionen zu verarbeiten:

Canvas(modifier = Modifier.fillMaxSize().windowInsetsPadding(WindowInsets.displayCutout)) {
    drawRect(Color.Red, style = Stroke(2.dp.toPx()))
}
CutoutSnippets.kt

Auf diese Weise können Sie das displayCutout-Padding bei Bedarf berücksichtigen oder ignorieren, wo es nicht erforderlich ist.

Alternativ können Sie dieselben Einstellungen anwenden, die in der Dokumentation zum Cutout beschrieben sind. Dazu legen Sie entweder das Aktivitätsthema android:windowLayoutInDisplayCutoutMode auf eine andere Option oder das Fensterattribut mit window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT fest. Der Ausschneidemodus wird dann jedoch auf die gesamte Aktivität angewendet und kann nicht für jede einzelne zusammensetzbare Funktion gesteuert werden.

Verwenden Sie WindowInset.displayCutout, um die Display-Aussparung bei bestimmten zusammensetzbaren Funktionen, bei anderen jedoch nicht zu berücksichtigen. Mit dieser API können Sie bei Bedarf auf die Ausschnittinformationen zugreifen.

Best Practices

Berücksichtigen Sie bei der Arbeit mit Display-Aussparungen Folgendes:

  • Achten Sie auf die Platzierung wichtiger Elemente der Benutzeroberfläche. Achten Sie darauf, dass wichtige Texte, Steuerelemente oder andere Informationen nicht durch den Aussparungsbereich verdeckt werden.
  • Platzieren oder erweitern Sie keine interaktiven Elemente, die eine detaillierte Erkennung erfordern, im Aussparungsbereich. Im Aussparungsbereich ist die Berührungsempfindlichkeit möglicherweise geringer.
  • Bei Beachtung der randlosen Anleitung finden Sie in den Einsätzen safeDrawing und safeContent Informationen zur Aussparung.
  • Verwende nach Möglichkeit Modifier.windowInsetsPadding(WindowInsets.safeDrawing), um den passenden Abstand für deine Inhalte festzulegen. Vermeiden Sie eine Hartcodierung der Höhe der Statusleiste, da dies zu Überlappungen oder abgeschnittenen Inhalten führen kann.

Mit Aussparungen testen, wie deine Inhalte gerendert werden

Testen Sie alle Bildschirme und Funktionen Ihrer App. Testen Sie dies nach Möglichkeit auf Geräten mit unterschiedlichen Aussparungen. Wenn Sie kein Gerät mit Aussparung haben, können Sie gängige Konfigurationen für die Aussparung auf jedem Gerät oder Emulator mit Android 9 oder höher simulieren:

  1. Aktivieren Sie Entwickleroptionen.
  2. Scrollen Sie auf dem Bildschirm Entwickleroptionen nach unten zum Abschnitt Zeichnung und wählen Sie Anzeige mit Ausschnitt simulieren aus.
  3. Wählen Sie die Art der Aussparung aus.
    Simulation einer Display-Aussparung im Emulator
    Abbildung 3: Mit Entwickleroptionen kannst du testen, wie deine Inhalte gerendert werden.