Wycinki w oknie tworzenia

Wycięcie w ekranie to obszar na niektórych urządzeniach, który wkracza w powierzchnię ekranu. Zapewnia to ekran od krawędzi do krawędzi, a jednocześnie pozostawia miejsce na ważne czujniki z przodu urządzenia.

Android obsługuje wycięcia w ekranie na urządzeniach z Androidem 9 (poziom interfejsu API 28) lub nowszym. Producenci urządzeń mogą jednak obsługiwać wycięcia na wyświetlaczu na urządzeniach z Androidem 8.1 lub starszym.

Na tej stronie opisano, jak w Compose zaimplementować obsługę urządzeń z wycięciem, w tym jak pracować z obszarem wycięcia, czyli prostokątem na powierzchni ekranu od krawędzi do krawędzi, który zawiera wycięcie.

Domyślny przypadek

Domyślnie wycięcia na wyświetlaczu są uwzględniane w informacjach o wstawkach okna. Dlatego jeśli zastosujesz się do wskazówek dotyczących tworzenia aplikacji sięgającej od krawędzi do krawędzi, nie będzie ona wyświetlać elementów w obszarach wycięcia.

Jeśli na przykład użyjesz funkcji Modifier.windowInsetsPadding(WindowInsets.safeContent) lub Modifier.windowInsetsPadding(WindowInsets.safeDrawing), aplikacja nie będzie automatycznie rysować w obszarach, w których znajduje się wycięcie. Obie te wartości (WindowInsets.safeContent i WindowInsets.safeDrawing) zawierają informacje o wycięciu w ekranie i nie będą wyświetlane w miejscu wycięcia na urządzeniu.

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

Aby dostosować to zachowanie, musisz samodzielnie zarządzać informacjami o wycięciu.

Ręczne zarządzanie informacjami o wycinkach

Możesz obsługiwać wycięcia na jeden z tych sposobów:

• Korzystanie z WindowInsets.displayCutout

• Ustawienie w pliku manifestu motywu za pomocą android:windowLayoutInDisplayCutoutMode

• Programowe ustawienie opcji w Window za pomocą window.attributes.layoutInDisplayCutoutMode

• Dostęp do obiektu wycinanki Path za pomocą LocalView.current.rootWindowInsets.displayCutout

W przypadku Compose zalecamy ustawienie wartości windowLayoutInDisplayCutoutMode na default w całościowym temacie, a potem użycie wartości WindowInsets.displayCutout do obsługi wstawek w komponentach:

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

Dzięki temu możesz zachować wypełnienie displayCutout tam, gdzie jest to wymagane, lub zignorować je tam, gdzie nie jest wymagane.

Możesz też zastosować te same ustawienia, które opisano w dokumentacji dotyczącej wycinka wyświetleń. Aby to zrobić, ustaw temat aktywności android:windowLayoutInDisplayCutoutMode na inną opcję lub zmień atrybut okna za pomocą tagu window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT. Jednak tryb wycinania jest wtedy stosowany do całej aktywności i nie można go kontrolować w poszczególnych komponentach.

Aby uwzględnić wycięcie w ekranie w niektórych składanych elementach, a w innych nie, użyj WindowInset.displayCutout. Ten interfejs API umożliwia dostęp do informacji o wycięciu w razie potrzeby.

Sprawdzone metody

Podczas pracy z wycinkami wyświetlacza należy wziąć pod uwagę te kwestie:

• Zwróć uwagę na rozmieszczenie kluczowych elementów interfejsu. Nie pozwól, aby obszar wycięcia zasłaniał ważny tekst, elementy sterujące ani inne informacje.
• Nie umieszczaj ani nie rozszerzaj elementów interaktywnych, które wymagają precyzyjnego wykrywania dotyku, w obszarze wycięcia. Czułość ekranu może być niższa w obszarze wycięcia.
• Jeśli postępujesz zgodnie ze wskazówkami dotyczącymi wyświetlania od krawędzi do krawędzi, informacje o wycięciu są uwzględniane w ramkach safeDrawing / safeContent.
• W miarę możliwości użyj elementu Modifier.windowInsetsPadding(WindowInsets.safeDrawing), aby określić odpowiedni margines dla treści. Unikaj twardego kodowania wysokości paska stanu, ponieważ może to spowodować nakładanie się lub przycinanie treści.

Testowanie renderowania treści z wycięciami

Przetestuj wszystkie ekrany i funkcje aplikacji. Jeśli to możliwe, przeprowadź test na urządzeniach z różnymi typami wycięć. Jeśli nie masz urządzenia z wycięciem, możesz symulować typowe konfiguracje wycięć na dowolnym urządzeniu lub emulatorze z Androidem 9 lub nowszym:

1. Włącz Opcje programisty.
2. Na ekranie Opcje programisty przewiń w dół do sekcji Rysowanie i wybierz Symuluj wyświetlacz z wcięciem.
3. Wybierz typ wycinania.