Ritagli in Scrivi

Un ritaglio del display è un'area su alcuni dispositivi che si estende nella superficie del display. Consente un'esperienza da bordo a bordo, offrendo al contempo spazio per importanti sensori 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 supportare anche i ritagli del display su dispositivi con Android 8.1 o versioni precedenti.

Questa pagina descrive come implementare il supporto per i dispositivi con ritagli in Compose, inclusa la modalità di utilizzo dell'area ritagliata, ovvero il rettangolo edge-to-edge sulla superficie del display che contiene il ritaglio.

Maiuscolo predefinito

Per impostazione predefinita, i ritagli del display sono inclusi nelle informazioni sugli inserti della finestra. Di conseguenza, l'app non verrà disegnata nelle aree del ritaglio del display se segui la guida per creare un'app edge-to-edge.

Ad esempio, quando utilizzi Modifier.windowInsetsPadding(WindowInsets.safeContent) o Modifier.windowInsetsPadding(WindowInsets.safeDrawing), la tua app non disegnerà automaticamente le aree in cui è posizionato un ritaglio. WindowInsets.safeContent e WindowInsets.safeDrawing contengono entrambi informazioni sul ritaglio del display e non verranno disegnati dove si trova il ritaglio del 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

Per personalizzare ulteriormente questo comportamento, devi gestire autonomamente le informazioni relative al ritaglio.

Gestire manualmente le informazioni relative al ritaglio

Puoi gestire i ritagli in uno dei seguenti modi:

• Utilizzo di WindowInsets.displayCutout

• Impostazione nel file manifest del tema con android:windowLayoutInDisplayCutoutMode

• Impostazione programmatica dell'opzione su un Window con window.attributes.layoutInDisplayCutoutMode

• Accesso all'oggetto ritaglio Path con LocalView.current.rootWindowInsets.displayCutout

Per Compose, ti consigliamo di impostare windowLayoutInDisplayCutoutMode su default nel tema generale e di utilizzare WindowInsets.displayCutout per gestire gli inserti nei composabili:

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

Questo approccio ti consente di rispettare il padding displayCutout dove necessario o ignorarlo dove non è necessario.

In alternativa, puoi applicare le stesse impostazioni descritte nella documentazione relativa al ritaglio delle visualizzazioni impostando il tema dell'attività android:windowLayoutInDisplayCutoutMode su un'altra opzione o impostando l'attributo finestra utilizzando window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT. Tuttavia, la modalità ritaglio viene applicata a un'intera attività e non può essere controllata per singolo composable.

Per rispettare il ritaglio del display in alcuni composabili, ma non in altri, utilizza WindowInset.displayCutout. Questa API ti consente di accedere alle informazioni sul ritaglio quando necessario.

Best practice

Quando utilizzi i ritagli del display, tieni presente quanto segue:

• Fai attenzione al posizionamento degli elementi critici dell'interfaccia utente. Non lasciare che l'area tagliata oscuri testo, controlli o altre informazioni importanti.
• Non posizionare o estendere elementi interattivi che richiedono un riconoscimento accurato all'interno dell'area ritagliata. La sensibilità al tocco potrebbe essere inferiore nell'area del ritaglio.
• Quando segui le indicazioni da bordo a bordo, le informazioni relative al ritaglio sono incluse negli inserti safeDrawing / safeContent.
• Se possibile, utilizza Modifier.windowInsetsPadding(WindowInsets.safeDrawing) per determinare il padding appropriato da applicare ai tuoi contenuti. Evita di impostare in modo rigido l'altezza della barra di stato, in quanto i contenuti potrebbero risultare sovrapposti o tagliati.

Testare il rendering dei contenuti con i ritagli

Assicurati di testare tutte le schermate e le esperienze dell'app. Se possibile, esegui il test su dispositivi con diversi tipi di ritagli. Se non hai un dispositivo con un'area tagliata, puoi simulare configurazioni comuni dell'area tagliata su qualsiasi dispositivo o emulatore con Android 9 o versioni successive seguendo questa procedura:

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