Ausschnitte in Compose

Eine Displayaussparung ist ein Bereich auf einigen Geräten, der sich über die Displayoberfläche erstreckt. Sie ermöglicht ein randloses Display und bietet gleichzeitig Platz für wichtige Sensoren auf der Vorderseite des Geräts.

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 Informationen zum Ausschnitt 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 Compose-Elementen berücksichtigen, aber in anderen nicht, 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 der Aussparung 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.
• Verwenden Sie nach Möglichkeit Modifier.windowInsetsPadding(WindowInsets.safeDrawing), um das passende Abstandselement für Ihre Inhalte zu bestimmen. 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 Funktionen Ihrer App. Testen Sie nach Möglichkeit auf Geräten mit unterschiedlichen 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 den Ausschnittstyp aus.