Ausschnitte in Compose

Bei einigen Geräten ist eine Display-Aussparung ein Bereich, der in die Displayoberfläche hineinreicht. So ist ein randloser Bildschirm möglich, während gleichzeitig Platz für wichtige Sensoren auf der Vorderseite des Geräts bleibt.

Abbildung 1: Beispiel für einen Ausschnitt im Hochformat

Abbildung 2: Beispiel für einen Ausschnitt im Querformat

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

Auf dieser Seite wird beschrieben, wie Sie in Compose Unterstützung für Geräte mit Ausschnitten implementieren. Außerdem erfahren Sie, wie Sie mit dem Ausschnittsbereich arbeiten, also dem Rechteck von Rand zu Rand auf der Displayoberfläche, das den Ausschnitt enthält.

Standardfall

Displayausschnitte sind standardmäßig in den Informationen zu Fenstereinblendungen enthalten. Wenn Sie der Anleitung folgen, um Ihre App bildschirmfüllend zu gestalten, werden die Displayausschnitte daher nicht dargestellt.

Wenn Sie beispielsweise Modifier.windowInsetsPadding(WindowInsets.safeContent) oder Modifier.windowInsetsPadding(WindowInsets.safeDrawing) verwenden, werden in Ihrer App die Bereiche, in denen sich ein Ausschnitt befindet, nicht automatisch dargestellt. Sowohl WindowInsets.safeContent als auch WindowInsets.safeDrawing enthalten Informationen zum Displayausschnitt und es wird nichts dort gezeichnet, wo sich ein Ausschnitt 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

Wenn Sie dieses Verhalten weiter anpassen möchten, müssen Sie die Ausschneideinformationen selbst verarbeiten.

Informationen zu Ausschnitten manuell verarbeiten

Sie haben folgende Möglichkeiten, mit Ausschnitten umzugehen:

• WindowInsets.displayCutout verwenden

• Im Designmanifest mit android:windowLayoutInDisplayCutoutMode festlegen

• Option programmatisch für einen Window mit window.attributes.layoutInDisplayCutoutMode festlegen

• Auf das Objekt „Ausschnitt“ Path mit LocalView.current.rootWindowInsets.displayCutout zugreifen

Für Compose wird empfohlen, windowLayoutInDisplayCutoutMode in Ihrem gesamten Design auf default festzulegen und dann WindowInsets.displayCutout zu verwenden, um die Einzüge in Ihren Compose-Elementen zu verwalten:

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

So können Sie das displayCutout-Abstand bei Bedarf berücksichtigen oder ignorieren, wenn es nicht erforderlich ist.

Alternativ können Sie dieselben Einstellungen wie in der Anleitung zum Ausschneiden von Aufrufen beschrieben anwenden. Legen Sie dazu entweder ein anderes Aktivitätsthema android:windowLayoutInDisplayCutoutMode fest oder verwenden Sie das Fensterattribut window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT. Der Ausschnittsmodus wird dann jedoch auf eine ganze Aktivität angewendet und kann nicht für einzelne Kompositionen gesteuert werden.

Wenn Sie den Displayausschnitt in bestimmten Composeable-Objekten berücksichtigen möchten, aber nicht in anderen, verwenden Sie WindowInset.displayCutout. Über diese API können Sie bei Bedarf auf die Informationen zum Ausschnitt zugreifen.

Best Practices

Beachten Sie bei der Arbeit mit Displayausschnitten Folgendes:

• Achten Sie auf die Platzierung wichtiger Elemente der Benutzeroberfläche. Achten Sie darauf, dass wichtige Textelemente, Steuerelemente oder andere Informationen nicht vom Ausschnitt verdeckt werden.
• Platzieren oder erweitern Sie keine interaktiven Elemente, die eine präzise Touch-Erkennung erfordern, in den Ausschnittsbereich. Im Bereich des Ausschnitts ist die Berührungsempfindlichkeit möglicherweise geringer.
• Wenn Sie der Anleitung für Displays ohne Ränder folgen, sind Informationen zu Ausschnitten in den Einblendungen safeDrawing / safeContent enthalten.
• Verwende nach Möglichkeit Modifier.windowInsetsPadding(WindowInsets.safeDrawing), um den geeigneten Abstand für deine Inhalte festzulegen. Die Höhe der Statusleiste sollte nicht hartcodiert werden, da dies zu überlappenden oder abgeschnittenen Inhalten führen kann.

Rendern von Inhalten mit Ausschnitten testen

Testen Sie alle Bildschirme und Nutzererfahrungen Ihrer App. Testen Sie dies nach Möglichkeit auf Geräten mit verschiedenen Aussparungen. Wenn Sie kein Gerät mit einer Aussparung haben, können Sie gängige Aussparungskonfigurationen 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 Abschnitt Zeichnen und wählen Sie Display mit Aussparung simulieren aus.
3. Wählen Sie die Art der Aussparung aus.

   

   Abbildung 3. Mit den Entwickleroptionen können Sie testen, wie Ihre Inhalte gerendert werden.