Recortes no Compose

Um corte da tela é uma área em alguns dispositivos que se estende até a superfície da tela. Ele permite uma experiência de ponta a ponta e, ao mesmo tempo, fornece espaço para sensores importantes na parte frontal do dispositivo.

O Android oferece suporte a cortes de tela em dispositivos com o Android 9 (nível 28 da API) ou mais recente. No entanto, os fabricantes de dispositivos também podem oferecer suporte a cortes de tela em dispositivos com Android 8.1 ou versões anteriores.

Esta página descreve como implementar o suporte a dispositivos com cortes no Compose, incluindo como trabalhar com a área de corte, ou seja, o retângulo de ponta a ponta na superfície da tela que contém o corte.

Caso padrão

Por padrão, os recortes de tela são incluídos nas informações de engastes de janela. Por isso, o app não será renderizado nas áreas de corte da tela quando você seguir o guia para fazer o app de ponta a ponta.

Por exemplo, quando você usa Modifier.windowInsetsPadding(WindowInsets.safeContent) ou Modifier.windowInsetsPadding(WindowInsets.safeDrawing), o app não é renderizado automaticamente nas áreas em que um recorte é colocado. WindowInsets.safeContent e WindowInsets.safeDrawing contêm informações sobre o corte na tela e não são exibidas onde há um corte no dispositivo.

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

Para personalizar ainda mais esse comportamento, você precisa processar as informações de recorte por conta própria.

Processar informações de recorte manualmente

É possível processar cortes das seguintes maneiras:

• Como usar o WindowInsets.displayCutout

• Configuração no manifesto do tema com android:windowLayoutInDisplayCutoutMode

• Definir a opção de maneira programática em um Window com window.attributes.layoutInDisplayCutoutMode

• Como acessar o objeto Path de corte com LocalView.current.rootWindowInsets.displayCutout

No Compose, é recomendável definir o windowLayoutInDisplayCutoutMode como default no tema geral e, em seguida, usar WindowInsets.displayCutout para processar os insets nos elementos combináveis:

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

Essa abordagem permite que você respeite o padding de displayCutout quando necessário ou o ignore quando não for necessário.

Como alternativa, é possível aplicar as mesmas configurações descritas na documentação de recorte de visualização definindo o tema de atividade android:windowLayoutInDisplayCutoutMode como outra opção ou definindo o atributo da janela usando window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT. No entanto, o modo de corte é aplicado a uma atividade inteira e não pode ser controlado por elemento combinável individual.

Para respeitar o corte da tela em determinados elementos combináveis, mas não em outros, use WindowInset.displayCutout. Essa API permite acessar as informações de recorte quando necessário.

Práticas recomendadas

Ao trabalhar com cortes de tela, considere o seguinte:

• Tenha cuidado com a colocação de elementos essenciais da interface. Não deixe a área de corte obscurecer textos, controles ou outras informações importantes.
• Não coloque nem estenda elementos interativos que exigem reconhecimento detalhado na área de corte. A sensibilidade ao toque pode ser menor na área de corte.
• Ao seguir a orientação de borda a borda, as informações de corte são incluídas nos insetos safeDrawing / safeContent.
• Sempre que possível, use Modifier.windowInsetsPadding(WindowInsets.safeDrawing) para determinar o padding adequado a ser aplicado ao conteúdo. Evite codificar a altura da barra de status, porque isso pode causar sobreposição ou corte de conteúdo.

Testar como seu conteúdo é renderizado com recortes

Teste todas as telas e experiências do seu app. Se possível, teste em dispositivos com diferentes tipos de corte. Se você não tem um dispositivo com corte, pode simular configurações de corte comuns em qualquer dispositivo ou emulador com o Android 9 ou versões mais recentes fazendo o seguinte:

1. Ative as Opções do desenvolvedor.
2. Na tela Opções do desenvolvedor, role para baixo até a seção Desenho e selecione Simular uma tela com corte.
3. Selecione o tipo de corte.