Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Ritagli display supportati

Un ritaglio display è un'area su alcuni dispositivi che si estende nella superficie del display. Consente un'esperienza edge-to-edge e offre spazio per i sensori importanti sulla parte anteriore del dispositivo.

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

Questo documento descrive come implementare il supporto per i dispositivi con intagli, incluso come utilizzare l'area dell'intaglio, ovvero il rettangolo da bordo a bordo sulla superficie del display che contiene l'intaglio.

Un'immagine che mostra un esempio di ritaglio display in alto al centro — **Figura 1.** 1 Ritaglio display.

Scegliere come l'app gestisce le aree di ritaglio

Se non vuoi che i tuoi contenuti si sovrappongano a un'area di ritaglio, in genere è sufficiente assicurarsi che non si sovrappongano alla barra di stato e alla barra di navigazione. Se esegui il rendering nell'area di ritaglio, utilizza WindowInsetsCompat.getDisplayCutout() per recuperare un oggetto DisplayCutout che contiene i margini 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 poterli riposizionare, se necessario.

Puoi anche determinare se i contenuti sono disposti dietro l'area di ritaglio. L'attributo layoutInDisplayCutoutMode del layout della finestra controlla il modo in cui i contenuti vengono visualizzati nell'area della tacca. Puoi impostare layoutInDisplayCutoutMode su uno dei seguenti valori:

LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: i contenuti vengono visualizzati nell'area di ritaglio quando il ritaglio display è contenuto in una barra di sistema. In caso contrario, la finestra non si sovrappone al ritaglio display. Ad esempio, i contenuti potrebbero essere visualizzati in formato letterbox quando vengono visualizzati in modalità Orizzontale. Se la tua app ha come target l'SDK 35, questo valore viene interpretato come ALWAYS per le finestre non mobili.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS: i contenuti possono sempre estendersi nelle aree di ritaglio. Se la tua app ha come target l'SDK 35 ed è in esecuzione su un dispositivo Android 15, questa è l'unica modalità consentita per le finestre non mobili per garantire una visualizzazione edge-to-edge.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: i contenuti vengono visualizzati nell'area di ritaglio sia in modalità verticale che orizzontale. Non utilizzare per le finestre mobili. Se la tua app ha come target l'SDK 35, questo valore viene interpretato come ALWAYS per le finestre non mobili.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: i contenuti non vengono mai visualizzati nell'area di ritaglio. Se la tua app ha come target l'SDK 35, questo valore viene interpretato come ALWAYS per le finestre non mobili.

Puoi impostare la modalità Ritaglio in modo programmatico o impostando uno stile nell'attività. Il seguente esempio 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 sezioni seguenti descrivono in modo più dettagliato le diverse modalità di ritaglio.

Comportamento predefinito

Se la tua app ha come target l'SDK 35 ed è in esecuzione su un dispositivo Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS è il comportamento predefinito e LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT viene interpretato come LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS per le finestre non mobili.

In caso contrario, il valore predefinito è LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT.

Visualizzare i contenuti nelle aree di ritaglio del lato corto

Se la tua app ha come target l'SDK 35 ed è in esecuzione su un dispositivo Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES viene interpretato come LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS per le finestre non mobili.

Con LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, i contenuti si estendono nell'area di ritaglio sul bordo corto del display sia in verticale che 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:

Un'immagine che mostra il rendering dei contenuti nell'area di ritaglio in modalità verticale — **Figura 2.** Rendering dei contenuti nell'area di ritaglio in modalità verticale.

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

Un'immagine che mostra il rendering dei contenuti nell'area di ritaglio in modalità orizzontale — **Figura 3.** Rendering dei contenuti nell'area di ritaglio in modalità orizzontale.

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

Un'incisione nell'angolo è considerata sul lato corto:

Un'immagine che mostra un dispositivo con un angolo tagliato — **Figura 4.** Un dispositivo con un'interruzione nell'angolo.

Non eseguire mai il rendering dei contenuti nell'area di ritaglio del display

Se la tua app ha come target l'SDK 35 ed è in esecuzione su un dispositivo Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER viene interpretato come LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS per le finestre non mobili.

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:

Un'immagine che mostra LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER per la modalità verticale — **Figura 5.** Esempio di `LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER` per la modalità Ritratto.

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

Un'immagine che mostra LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER per l'orientamento orizzontale — **Figura 6.** Esempio di `LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER` in modalità orizzontale.

Best practice per il supporto del ritaglio display

Quando lavori con le tacche del display, tieni presente quanto segue:

Presta attenzione al posizionamento degli elementi critici dell'UI. Non lasciare che l'area di ritaglio oscuri testo, controlli o altre informazioni importanti.
Non posizionare o estendere elementi interattivi che richiedono il riconoscimento del tocco preciso nell'area di ritaglio. La sensibilità al tocco potrebbe essere inferiore nell'area di ritaglio.
Se possibile, utilizza WindowInsetsCompat per recuperare l'altezza della barra di stato e determinare il padding appropriato da applicare ai tuoi contenuti. Evita di codificare l'altezza della barra di stato, in quanto ciò può comportare la sovrapposizione o il taglio dei contenuti.

Figura 7. Utilizza WindowInsetsCompat per evitare sovrapposizioni o tagli dei contenuti.
Utilizza View.getLocationInWindow() per determinare la quantità di spazio della finestra utilizzata dall'app. Non dare per scontato che l'app utilizzi l'intera finestra e non utilizzare View.getLocationOnScreen().
Utilizza le modalità di ritaglio always, shortEdges o never se la tua app deve passare alla modalità immersiva e uscire da questa modalità. Il comportamento predefinito del ritaglio può causare il rendering dei contenuti dell'app nell'area del ritaglio mentre le barre di sistema sono presenti, ma non in modalità immersiva. Di conseguenza, i contenuti si spostano verso l'alto e verso il basso durante le transizioni, come dimostrato nell'esempio seguente.

Figura 8. Esempio di contenuti che si spostano verso l'alto e verso il basso durante le transizioni.
In modalità immersiva, fai attenzione a utilizzare le coordinate della finestra rispetto a quelle dello schermo, poiché la tua app non utilizza l'intero schermo quando è in formato letterbox. A causa del letterbox, le coordinate dall'origine dello schermo non sono le stesse delle coordinate dall'origine della finestra. Puoi trasformare le coordinate dello schermo in coordinate della visualizzazione in base alle esigenze utilizzando getLocationOnScreen(). L'immagine seguente mostra la differenza tra le coordinate quando i contenuti sono in letterbox:

Figura 9. Coordinate della finestra rispetto a quelle dello schermo quando i contenuti sono in formato letterbox.
Quando gestisci MotionEvent, utilizza MotionEvent.getX() e MotionEvent.getY() per evitare problemi simili con le coordinate. Non utilizzare MotionEvent.getRawX() o MotionEvent.getRawY().

Testare il rendering dei contenuti

Testa tutte le schermate e le esperienze della tua app. Se possibile, esegui test su dispositivi con diversi tipi di ritagli. Se non hai un dispositivo con un'area di visualizzazione interrotta, puoi simulare configurazioni comuni di interruzione su qualsiasi dispositivo o emulatore che esegue Android 9 o versioni successive procedendo nel seguente modo:

Attiva Opzioni sviluppatore.
Nella schermata Opzioni sviluppatore, scorri verso il basso fino alla sezione Disegno e seleziona Simula un display con un ritaglio.
Seleziona il tipo di ritaglio.

Figura 10. Opzioni sviluppatore per testare il rendering dei contenuti.