Ritagli display supportati

Prova la modalità Scrivi

Jetpack Compose è il toolkit dell'interfaccia utente consigliato per Android. Scopri come lavorare con i ritagli del display in Compose.

Visualizza i ritagli in Compose →

Un ritaglio del display è un'area di alcuni dispositivi che si estende fino alla superficie del display. Offre un'esperienza a livello perimetrale, offrendo allo stesso tempo spazio per sensori importanti sulla parte anteriore del dispositivo.

Android supporta i ritagli del display sui dispositivi con Android 9 (livello API 28) e versioni successive. Tuttavia, i produttori di dispositivi possono anche supportare i ritagli del display sui dispositivi con Android 8.1 o versioni precedenti.

Questo documento descrive come implementare il supporto per i dispositivi con ritagli, incluso come lavorare con l'area di taglio, ovvero il rettangolo bordo a bordo sulla superficie del display che contiene il ritaglio.

Scegliere in che modo l'app gestisce le aree di ritaglio

Se non vuoi che i contenuti si sovrappongano a un'area di ritaglio, è sufficiente assicurarsi che non si sovrappongano alla barra di stato e alla barra di navigazione. Se esegui il rendering nell'area di ritaglio, usa WindowInsetsCompat.getDisplayCutout() per recuperare un oggetto DisplayCutout contenente gli insiemi sicuri e il riquadro di delimitazione per ogni ritaglio. Queste API ti consentono di verificare se i tuoi contenuti si sovrappongono al ritaglio in modo da poter riposizionare, se necessario.

Puoi anche stabilire se i contenuti sono disposti dietro l'area di ritaglio. L'attributo di layout della finestra layoutInDisplayCutoutMode controlla in che modo i contenuti vengono disegnati nell'area di ritaglio. Puoi impostare layoutInDisplayCutoutMode su uno dei seguenti valori:

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: i contenuti vengono visualizzati nell'area di ritaglio quando vengono visualizzati in modalità verticale, ma i contenuti vengono adattati al formato letterbox quando sono visualizzati in modalità Orizzontale.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: i contenuti vengono visualizzati nell'area di ritaglio in modalità verticale e orizzontale.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: i contenuti non vengono mai visualizzati nell'area di ritaglio.

Puoi impostare la modalità di ritaglio in modo programmatico o impostando uno stile nell'attività. L'esempio seguente definisce uno stile per applicare l'attributo LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES all'attività.

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

Le seguenti sezioni descrivono in maggiore dettaglio le diverse modalità di ritaglio.

Comportamento predefinito

Per impostazione predefinita, in modalità verticale senza alcun flag speciale impostato, la barra di stato su un dispositivo con un ritaglio viene ridimensionata in modo che sia alta almeno quanto il ritaglio e i contenuti vengono visualizzati nell'area sottostante. In modalità Orizzontale o a schermo intero, la finestra dell'app è letterbox in modo che nessuno dei tuoi contenuti venga visualizzato nell'area di ritaglio.

Visualizza i contenuti in aree di ritaglio dal bordo corto

Per alcuni contenuti, come video, foto, mappe e giochi, il rendering nell'area di ritaglio può essere un ottimo modo per offrire agli utenti un'esperienza più immersiva e a livello perimetrale. Con LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, i contenuti si estendono nell'area di ritaglio sul bordo corto del display sia in verticale sia in orizzontale, indipendentemente dal fatto che le barre di sistema siano nascoste o visibili. Quando utilizzi questa modalità, assicurati che nessun contenuto importante si sovrapponga all'area di ritaglio.

La seguente immagine è un esempio di LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES per un dispositivo in verticale:

La seguente immagine è un esempio di LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES per un dispositivo in orizzontale:

In questa modalità, la finestra si estende sotto i ritagli sul bordo corto del display sia in verticale sia in orizzontale, indipendentemente dal fatto che la finestra nasconda le barre di sistema.

Un ritaglio nell'angolo è considerato sul lato corto:

Non visualizzare mai i contenuti nell'area di ritaglio del display

Con LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, la finestra non può mai sovrapporsi all'area di ritaglio.

Di seguito è riportato un esempio di LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER in verticale:

Di seguito è riportato un esempio di LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER in modalità Orizzontale:

Best practice per il supporto del ritaglio display

Quando lavori con ritagli del display, considera quanto segue:

• Presta attenzione al posizionamento degli elementi critici dell'interfaccia utente. Non lasciare che l'area del ritaglio copra testo, controlli o altre informazioni importanti.
• Non posizionare o estendere nell'area di ritaglio eventuali elementi interattivi che richiedono il riconoscimento tramite tocco. La sensibilità del tocco potrebbe essere più bassa nell'area del taglio.

• Se possibile, utilizza WindowInsetsCompat per recuperare l'altezza della barra di stato e determinare la spaziatura interna appropriata da applicare ai contenuti. Evita l'hardcoded dell'altezza della barra di stato, poiché ciò potrebbe causare la sovrapposizione o l'interruzione dei contenuti.

  

• Utilizza View.getLocationInWindow() per determinare la quantità di spazio nella finestra utilizzata dalla tua app. Non dare per scontato che l'app utilizzi l'intera finestra e non usare View.getLocationOnScreen().

• Utilizza le modalità di ritaglio shortEdges o never se la tua app deve attivare e disattivare la modalità immersiva. Il comportamento predefinito del ritaglio può causare il rendering dei contenuti nell'app nell'area di ritaglio quando sono presenti le barre di sistema, ma non in modalità immersiva. Di conseguenza, i contenuti si spostano verso l'alto o verso il basso durante le transizioni, come mostrato nell'esempio che segue.

  

• Nella modalità immersiva, fai attenzione a utilizzare le coordinate di finestra e schermo, dato che l'app non utilizza l'intero schermo quando viene adattata al formato letterbox. A causa della letterbox, le coordinate dell'origine della schermata non corrispondono alle coordinate dell'origine della finestra. Puoi trasformare le coordinate dello schermo in coordinate della vista in base alle tue esigenze utilizzando getLocationOnScreen(). La seguente immagine mostra la differenza tra le coordinate quando i contenuti vengono adattati al formato letterbox:

  

• Quando gestisci MotionEvent, usa MotionEvent.getX() e MotionEvent.getY() per evitare problemi di coordinate simili. Non usare MotionEvent.getRawX() o MotionEvent.getRawY().

Testare il modo in cui vengono visualizzati i contenuti

Testa tutte le schermate e le esperienze della tua app. Se possibile, fai dei test su dispositivi con diversi tipi di ritagli. Se non hai un dispositivo con un ritaglio, puoi simulare le configurazioni di ritaglio comuni su qualsiasi dispositivo o emulatore con Android 9 o versioni successive procedendo nel seguente modo:

1. Attiva le Opzioni sviluppatore.
2. Nella schermata Opzioni sviluppatore, scorri verso il basso fino alla sezione Disegno e seleziona Simula un display con ritaglio.

3. Seleziona il tipo di ritaglio.

   

Risorse aggiuntive

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES