Compatibilidade com cortes da tela

Um corte da tela é uma área em alguns dispositivos que se estende até a superfície da tela para possibilitar uma experiência de ponta a ponta, deixando espaço para sensores importantes na parte frontal do dispositivo. O Android é oficialmente compatível com cortes da tela em dispositivos com o Android 9 (API de nível 28) ou versões posteriores. Fabricantes de dispositivos também podem optar por oferecer compatibilidade com cortes da tela em dispositivos com Android 8.1 ou versões anteriores.

Este tópico descreve como implementar compatibilidade em dispositivos com esses cortes, incluindo como trabalhar com área de cortes, ou seja, o retângulo de ponta a ponta na superfície da tela que contém o corte.

O que esperar em dispositivos com cortes da tela

Para garantir a consistência e a compatibilidade com os apps, os dispositivos com o Android 9 precisam garantir o seguinte comportamento de corte:

• Uma única borda pode conter no máximo um corte.
• Um dispositivo não pode ter mais que dois cortes.
• Um dispositivo não pode ter cortes em nenhuma das suas bordas maiores.
• Na orientação retrato, sem sinalizações especiais definidas, a barra de status precisa ser estendida até pelo menos a altura do corte.
• Por padrão, no modo tela cheia ou na orientação paisagem, toda a área de corte precisa estar com efeito letterbox.

Escolher como o app processa áreas de corte

Para que seu conteúdo não se sobreponha a uma área de corte, normalmente é suficiente apenas garantir que o conteúdo não se sobreponha à barra de status e à barra de navegação. Se estiver renderizando na área de corte, você pode usar WindowInsets.getDisplayCutout() para recuperar um objeto DisplayCutout que contenha as inserções e a caixa delimitadoras seguras para cada corte. Essas APIs permitem que você verifique se seu conteúdo se sobrepõe ao corte para que seja possível reposicioná-lo, se necessário.

O Android também permite controlar se o conteúdo será exibido dentro da área de corte. O atributo de layout de janela layoutInDisplayCutoutMode controla como o conteúdo é desenhado na área de corte. Você pode definir layoutInDisplayCutoutMode como um dos seguintes valores:

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: esse é o comportamento padrão, conforme descrito acima. O conteúdo é renderizado na área de corte no modo retrato, mas é exibido com efeito letterbox no modo paisagem.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: o conteúdo é renderizado na área de corte nos modos retrato e paisagem.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: o conteúdo nunca é renderizado na área de corte.

Você pode definir o modo de corte de forma programática ou definindo um estilo na sua atividade. O exemplo abaixo define um estilo que pode ser usado para aplicar o atributo LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES à atividade.

    <style name="ActivityTheme">
      <item name="android:windowLayoutInDisplayCutoutMode">
        shortEdges <!-- default, shortEdges, never -->
      </item>
    </style>
    

As seções abaixo descrevem os diferentes modos de corte em mais detalhes.

Comportamento padrão

Por padrão, no modo retrato sem sinalizações especiais definidas, a barra de status em um dispositivo com corte é redimensionada para ser pelo menos tão alta quanto o corte, e o conteúdo é exibido na área abaixo. No modo paisagem ou tela cheia, a janela do app tem efeito letterbox para que nenhum conteúdo seja exibido na área de corte.

Renderizar conteúdo em áreas de corte de borda curta

Para alguns conteúdos, como vídeos, fotos, mapas e jogos, a renderização na área de corte pode ser uma ótima maneira de oferecer uma experiência mais imersiva e de ponta a ponta para os usuários. Com LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, o conteúdo se estende até a área de corte na borda curta da tela, tanto no modo retrato quanto paisagem, independentemente de se as barras do sistema estão ocultas ou visíveis. A janela nunca pode se estender para uma área de corte nas bordas longas da tela. Ao usar esse modo, verifique se nenhum conteúdo importante se sobrepõe à área de corte.

O Android pode não permitir que a visualização de conteúdo se sobreponha às barras do sistema. Para modificar esse comportamento e forçar o conteúdo a se estender até a área de corte, aplique qualquer uma das seguintes sinalizações à visibilidade da visualização por meio do método View.setSystemUiVisibility(int):

• SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
• SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
• SYSTEM_UI_FLAG_LAYOUT_STABLE

Veja alguns exemplos de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES:

Considera-se que um corte no canto esteja na lateral pequena do dispositivo; portanto, o mesmo comportamento se aplica:

Nunca renderize conteúdo na área de corte da tela

Com LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, nunca é permitido que a janela se sobreponha à área de corte.

Esse modo é usado com janelas que temporariamente definem View.SYSTEM_UI_FLAG_FULLSCREEN ou View.SYSTEM_UI_FLAG_HIDE_NAVIGATION para evitar a execução de outro layout da janela quando a sinalização for definida ou apagada.

Veja exemplos de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER abaixo.

Modo especial

Alguns dispositivos com o Android 8.1 (API de nível 27) ou versões anteriores são compatíveis com um modo especial que permite que os usuários estendam um app em tela cheia ou modo paisagem com efeito letterbox para a área de corte. Esse modo normalmente é controlado com um botão de ativação na barra de navegação que apresenta uma caixa de diálogo que solicita uma confirmação antes de estender a tela.

Práticas recomendadas para a compatibilidade com corte de tela

Ao trabalhar com cortes da tela, considere o seguinte:

• Não deixe a área de corte obscurecer textos, controles ou outras informações importantes.
• Não coloque ou estenda elementos interativos que exigem um bom reconhecimento de toque na área de corte. A sensibilidade ao toque pode ser menor na área de corte.

• Evite codificar a altura da barra de status, porque isso pode causar sobreposição ou corte de conteúdos. Quando possível, use WindowInsetsCompat para recuperar a altura da barra de status e determinar o padding adequado a ser aplicado ao conteúdo.

  

• Não presuma que o app terá a janela inteira. Em vez disso, confirme o local usando View.getLocationInWindow(). Não use View.getLocationOnScreen().

• Processe as transições do modo de tela cheia de forma adequada. esta postagem do Blog de desenvolvedores Android.

• Com o comportamento de corte padrão no modo retrato, se a área de corte estiver na borda superior e a janela não tiver definido FLAG_FULLSCREEN ou View.SYSTEM_UI_FLAG_FULLSCREEN, a janela poderá se estender até a área de corte. Da mesma forma, se a área de corte estiver na borda inferior e a janela não tiver definido View.SYSTEM_UI_FLAG_HIDE_NAVIGATION, a janela poderá se estender até a área de corte. Nos modos tela cheia ou paisagem, a janela é disposta de modo que não se sobreponha à área de corte.

• Use os modos de corte shortEdges ou never se o app precisar fazer a transição para o modo de tela cheia. O comportamento de corte padrão pode fazer com que o conteúdo do app se mova para cima e para baixo durante as transições, conforme demonstrado na imagem abaixo.

  

• No modo tela cheia, tenha cuidado ao usar as coordenadas entre janela e tela, porque o app não ocupa a tela toda quando está com efeito letterbox. As coordenadas da origem da tela não são mais as mesmas que as da origem da janela devido ao efeito letterbox. Você pode transformar as coordenadas da tela em coordenadas da visualização, conforme necessário, usando getLocationOnScreen(). A imagem abaixo mostra como as coordenadas diferem quando o conteúdo está com efeito letterbox.

  

  Ao processar MotionEvent, use MotionEvent.getX() e MotionEvent.getY() para evitar problemas de coordenadas semelhantes. Não use MotionEvent.getRawX() ou MotionEvent.getRawY().

Testar como seu conteúdo é renderizado

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 algumas configurações de corte comuns em qualquer dispositivo ou emulador com o Android 9 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.