Supporto di pieghe a tre ante e pieghevoli orizzontali

Gli sviluppatori spesso incontrano difficoltà uniche quando creano applicazioni per dispositivi pieghevoli, in particolare dispositivi come Samsung Trifold o il Pixel Fold originale, che si apre in formato orizzontale (rotation_0 = landscape). Gli errori degli sviluppatori includono:

• Ipotesi errate sull'orientamento del dispositivo
• Casi d'uso trascurati
• Mancato ricalcolo o memorizzazione nella cache dei valori in seguito a modifiche alla configurazione

I problemi specifici relativi al dispositivo includono:

• Una mancata corrispondenza nell'orientamento naturale del dispositivo tra la cover e i display interni (presupposti basati su rotation_0 = verticale), che causa l'arresto anomalo delle app durante l'apertura e la chiusura
• Gestione di diverse densità dello schermo e modifiche errate alla configurazione della densità
• Problemi di anteprima della videocamera causati dalla dipendenza del sensore della videocamera dall'orientamento naturale

Per offrire un'esperienza utente di alta qualità sui dispositivi pieghevoli, concentrati sulle seguenti aree critiche:

• Determina l'orientamento dell'app in base all'area dello schermo effettiva occupata dall'app, non all'orientamento fisico del dispositivo
• Aggiorna le anteprime delle videocamere per gestire correttamente l'orientamento e le proporzioni del dispositivo, evitare anteprime laterali e impedire immagini allungate o ritagliate
• Mantenere la continuità dell'app durante la chiusura o l'apertura del dispositivo mantenendo lo stato con ViewModel o approcci simili oppure gestendo manualmente le modifiche della densità dello schermo e dell'orientamento, il che evita riavvii dell'app o perdita di stato
• Per le app che utilizzano sensori di movimento, regola il sistema di coordinate in modo che sia allineato all'orientamento attuale dello schermo ed evita ipotesi basate su rotation_0 = verticale, garantendo interazioni precise con l'utente.

Build adattiva

Se la tua app è già adattabile e rispetta il livello ottimizzato (livello 2) descritto nelle linee guida relative alla qualità delle app per schermi di grandi dimensioni, dovrebbe funzionare bene sui dispositivi pieghevoli. In caso contrario, prima di ricontrollare i dettagli specifici dei pieghevoli a tre ante e orizzontali, rivedi i seguenti concetti di base dello sviluppo adattivo per Android.

Layout adattivi

La tua UI deve gestire non solo le diverse dimensioni dello schermo, ma anche le modifiche in tempo reale delle proporzioni, ad esempio l'apertura e l'inserimento di modalità multi-finestra o di finestre del computer. Consulta la sezione Informazioni sui layout adattivi per ulteriori indicazioni su come:

• Progettare e implementare layout adattivi
• Regolare la navigazione principale dell'app in base alle dimensioni della finestra
• Utilizzare le classi di dimensioni delle finestre per adattare la UI dell'app
• Semplifica l'implementazione di layout canonici, come l'elenco dettagliato, utilizzando le API Jetpack

Classi di dimensioni dello schermo

I dispositivi pieghevoli, inclusi quelli pieghevoli orizzontali e i trifold, possono passare istantaneamente dalle classi di dimensioni delle finestre compatte, medie ed espanse. La comprensione e l'implementazione di queste classi garantiscono che l'app mostri i componenti di navigazione e la densità dei contenuti corretti per lo stato attuale del dispositivo.

L'esempio seguente utilizza la libreria adattiva Material 3 per determinare lo spazio disponibile per l'app richiamando prima la funzione currentWindowAdaptiveInfo(), quindi utilizzando i layout corrispondenti per le tre classi di dimensioni della finestra:

val adaptiveInfo = currentWindowAdaptiveInfo(supportLargeAndXLargeWidth = true)
val windowSizeClass = adaptiveInfo.windowSizeClass

when {
  windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_EXPANDED_LOWER_BOUND) -> // Large
  windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND) -> // Medium
  else -> // Compact
}

Per ulteriori informazioni, vedi Utilizzare le classi di dimensioni della finestra.

Qualità delle app per schermi di grandi dimensioni

Il rispetto del livello 2 (ottimizzato per schermi di grandi dimensioni) o del livello 1 (differenziato per schermi di grandi dimensioni) delle linee guida per la qualità delle app per schermi di grandi dimensioni garantisce che la tua app offra un'esperienza utente coinvolgente su dispositivi pieghevoli a tre ante, pieghevoli orizzontali e altri dispositivi con schermi di grandi dimensioni. Le linee guida coprono controlli critici su più livelli per passare da un'esperienza adattiva a un'esperienza differenziata.

Android 16 e versioni successive

Per le app che hanno come target Android 16 (livello API 36) e versioni successive, il sistema ignora le limitazioni di orientamento, ridimensionamento e proporzioni sui display con larghezza minima >= 600 dp. Le app riempiono l'intera finestra di visualizzazione, indipendentemente dalle proporzioni o dall'orientamento preferito dall'utente, e la modalità di compatibilità letterbox non viene più utilizzata.

Considerazioni speciali

I dispositivi pieghevoli a tre ante e orizzontali introducono comportamenti hardware unici che richiedono una gestione specifica, in particolare per quanto riguarda sensori, anteprima della fotocamera e continuità della configurazione (mantenimento dello stato durante la chiusura, l'apertura o il ridimensionamento).

Anteprima fotocamera

Un problema comune sui dispositivi pieghevoli orizzontali o nei calcoli delle proporzioni (in scenari come multi-finestra, finestre del desktop o display collegati) si verifica quando l'anteprima della videocamera appare allungata, laterale, ritagliata o ruotata.

Presupposti non corrispondenti

Questo problema si verifica spesso su dispositivi con schermi di grandi dimensioni e pieghevoli perché le app possono presupporre relazioni fisse tra le funzionalità della fotocamera, come le proporzioni e l'orientamento del sensore, e le funzionalità del dispositivo, come l'orientamento del dispositivo e l'orientamento naturale.

I nuovi fattori di forma mettono in discussione questo presupposto. Un dispositivo pieghevole può modificare le dimensioni e le proporzioni del display senza che la rotazione del dispositivo cambi. Ad esempio, l'apertura di un dispositivo ne modifica le proporzioni, ma se l'utente non ruota il dispositivo, la rotazione rimane la stessa. Se un'app presuppone che le proporzioni siano correlate alla rotazione del dispositivo, potrebbe ruotare o scalare in modo errato l'anteprima della videocamera. Lo stesso può accadere se un'app presuppone che l'orientamento del sensore della videocamera corrisponda a un orientamento verticale del dispositivo, il che non è sempre vero per i pieghevoli orizzontali.

Soluzione 1: Jetpack CameraX (migliore)

La soluzione più semplice e solida è utilizzare la libreria Jetpack CameraX. Il suo elemento PreviewView UI è progettato per gestire automaticamente tutte le complessità dell'anteprima:

• PreviewView si adatta correttamente all'orientamento del sensore, alla rotazione del dispositivo e al ridimensionamento.
• Mantiene le proporzioni dell'immagine della videocamera, in genere centrando e ritagliando (FILL_CENTER).
• Puoi impostare il tipo di scala su FIT_CENTER per aggiungere bande nere all'anteprima, se necessario.

Per saperne di più, consulta la sezione Implementare un'anteprima nella documentazione di CameraX.

Soluzione 2: CameraViewfinder

Se utilizzi una codebase Camera2 esistente, la libreria CameraViewfinder (compatibile con le versioni precedenti fino al livello API 21) è un'altra soluzione moderna. Semplifica la visualizzazione del feed della videocamera utilizzando TextureView o SurfaceView e applicando tutte le trasformazioni necessarie (proporzioni, scala e rotazione) per te.

Per ulteriori informazioni, consulta il post del blog Introducing Camera Viewfinder e la guida per gli sviluppatori Anteprima della videocamera.

Soluzione 3: implementazione manuale di Camera2

Se non puoi utilizzare CameraX o CameraViewfinder, devi calcolare manualmente l'orientamento e le proporzioni e assicurarti che i calcoli vengano aggiornati a ogni modifica della configurazione:

• Ottieni l'orientamento del sensore della videocamera (ad esempio 0, 90, 180, 270 gradi) da CameraCharacteristics.
• Ottieni la rotazione attuale del display del dispositivo (ad esempio, 0, 90, 180, 270 gradi).
• Utilizza questi due valori per determinare le trasformazioni necessarie per il tuo SurfaceView o TextureView.
• Assicurati che le proporzioni dell'output Surface corrispondano a quelle dell'anteprima della videocamera per evitare distorsioni.
• L'app Fotocamera potrebbe essere in esecuzione in una parte dello schermo, in modalità multi-finestra o a finestre del computer oppure su un display connesso. Per questo motivo, le dimensioni dello schermo non devono essere utilizzate per determinare le dimensioni del mirino della videocamera. Utilizza invece le metriche della finestra.

Per ulteriori informazioni, consulta la guida per gli sviluppatori Anteprima della videocamera e il video L'app Fotocamera su diversi fattori di forma.

Soluzione 4: esegui azioni di base della fotocamera utilizzando un intent

Se non hai bisogno di molte funzionalità della fotocamera, una soluzione semplice e diretta è eseguire azioni di base della fotocamera, come scattare una foto o registrare un video utilizzando l'applicazione fotocamera predefinita del dispositivo. Non è necessario eseguire l'integrazione con una libreria di videocamere; utilizza invece un intent.

Per ulteriori informazioni, vedi Intent della videocamera.

Configurazione e continuità

I dispositivi pieghevoli migliorano la versatilità dell'interfaccia utente, ma possono avviare più modifiche alla configurazione rispetto a quelli non pieghevoli. La tua app deve gestire queste modifiche alla configurazione e le relative combinazioni, come la rotazione del dispositivo, l'apertura/chiusura e il ridimensionamento della finestra nelle modalità multi-finestra o desktop, mantenendo o ripristinando lo stato dell'app. Ad esempio, le app devono mantenere la seguente continuità:

• Stato dell'app senza arresti anomali o modifiche disruptive per gli utenti (ad esempio, quando si cambia schermata o si invia l'app in background)
• Posizione di scorrimento dei campi scorrevoli
• Testo digitato nei campi di testo e stato della tastiera
• Posizione di riproduzione dei contenuti multimediali, in modo che la riproduzione riprenda da dove era stata interrotta quando è stata avviata la modifica della configurazione

Le modifiche alla configurazione attivate di frequente includono screenSize, smallestScreenSize, screenLayout, orientation, density, fontScale, touchscreen e keyboard.

Consulta android:configChanges e Gestire le modifiche alla configurazione. Per ulteriori informazioni sulla gestione dello stato dell'app, consulta Salvare gli stati dell'interfaccia utente.

Modifiche alla configurazione della densità

Gli schermi esterno e interno dei dispositivi pieghevoli a tre ante e orizzontali potrebbero avere densità di pixel diverse. Pertanto, la gestione della modifica della configurazione per density richiede maggiore attenzione. Android in genere riavvia l'attività quando la densità di visualizzazione cambia, il che può causare la perdita di dati. Per impedire al sistema di riavviare l'attività, dichiara la gestione della densità nel manifest e gestisci la modifica della configurazione a livello di programmazione nella tua app.

Configurazione di AndroidManifest.xml

• density: dichiara che l'app gestirà la modifica della densità dello schermo
• Altre modifiche alla configurazione: è anche consigliabile dichiarare altre modifiche alla configurazione che si verificano di frequente, ad esempio screenSize, orientation, keyboardHidden, fontScale e così via.

La dichiarazione della densità (e di altre modifiche alla configurazione) impedisce al sistema di riavviare l'attività e chiama invece onConfigurationChanged().

Implementazione di onConfigurationChanged()

Quando si verifica una modifica della densità, devi aggiornare le risorse (ad esempio ricaricando le bitmap o ricalcolando le dimensioni del layout) nel callback:

• Verifica che il DPI sia stato modificato in newConfig.densityDpi
• Reimposta le visualizzazioni personalizzate, le risorse disegnabili personalizzate e così via sulla nuova densità

Elementi delle risorse da elaborare

• Risorsa immagine: sostituisci bitmap e drawables con risorse specifiche per la densità o regola direttamente la scala
• Unità di layout (conversione da dp a px): ricalcola dimensioni, margine e spaziatura interna della visualizzazione
• Dimensioni del carattere e del testo: applica nuovamente le dimensioni del testo dell'unità sp
• Disegno personalizzato View/Canvas: aggiorna i valori basati sui pixel utilizzati per disegnare Canvas

Determinare l'orientamento dell'app

Non fare mai affidamento sulla rotazione fisica del dispositivo quando crei app adattive, perché verrà ignorata sui dispositivi con schermi grandi e un'app in modalità multi-finestra potrebbe avere un orientamento diverso da quello del dispositivo. Utilizza invece Configuration.orientation o WindowMetrics per identificare se la tua app è attualmente in orientamento orizzontale o verticale in base alle dimensioni della finestra.

Soluzione 1: utilizza Configuration.orientation

Questa proprietà identifica l'orientamento in cui viene attualmente visualizzata la tua app.

Soluzione 2: utilizza WindowMetrics#getBounds()

Puoi ottenere i limiti di visualizzazione correnti dell'app e controllare la larghezza e l'altezza per determinare l'orientamento.

Se devi limitare l'orientamento delle app sugli smartphone (o sugli schermi esterni dei dispositivi pieghevoli) ma non sui dispositivi con schermi grandi, consulta Limitare l'orientamento delle app sugli smartphone.

Posture e modalità di visualizzazione

Le posture e gli stati pieghevoli, come la modalità Tavolo e HALF_OPENED, sono supportati sia dai pieghevoli verticali che da quelli orizzontali. Le cover a libro, invece, non supportano la postura a cavalletto e non possono essere utilizzate HALF_OPENED. I pieghevoli invece offrono uno schermo più grande per un'esperienza utente unica quando sono completamente aperti.

Per differenziare la tua app sui dispositivi pieghevoli che supportano HALF_OPENED, utilizza le API Jetpack WindowManager, ad esempio FoldingFeature.

Scopri di più su posture, stati e supporto per l'anteprima della videocamera nei seguenti guide per gli sviluppatori:

• Scopri di più sui dispositivi pieghevoli
• Rendere l'app consapevole della piega

I dispositivi pieghevoli offrono esperienze di visualizzazione uniche. La modalità Display posteriore e la modalità Dual Screen ti consentono di creare funzionalità di visualizzazione speciali per i dispositivi pieghevoli, come l'anteprima dei selfie con la fotocamera posteriore e visualizzazioni simultanee ma diverse sugli schermi interno ed esterno. Per saperne di più, consulta:

• Supportare le modalità di visualizzazione pieghevoli

Blocco dell'orientamento sull'orientamento naturale del sensore

Per casi d'uso molto specifici, in particolare per le app che devono occupare l'intero schermo indipendentemente dallo stato di chiusura del dispositivo, il flag nosensor consente di bloccare l'app sull'orientamento naturale del dispositivo. Ad esempio, su Pixel Fold, l'orientamento naturale del dispositivo quando è chiuso è verticale, mentre l'orientamento naturale quando è aperto è orizzontale. L'aggiunta del flag nosensor forza il blocco dell'app in verticale quando viene eseguita sul display esterno e in orizzontale quando viene eseguita sul display interno.

<activity
  android:name=".MainActivity"
  android:screenOrientation="nosensor">

Rimappatura dei sensori XR e dei giochi

Per i giochi e le app XR, i dati dei sensori non elaborati (come giroscopio o accelerometro) vengono forniti nel sistema di coordinate fisso del dispositivo. Se l'utente ruota il dispositivo per giocare in orizzontale, gli assi del sensore non ruotano con lo schermo, il che comporta controlli di gioco errati.

Per risolvere il problema, controlla l'attuale Display.getRotation() e rimappa gli assi di conseguenza:

• Rotazione 0: x=x, y=y
• Rotazione di 90°: x=-y, y=x
• Rotazione di 180°: x=-x, y=-y
• Rotazione 270: x=y, y=-x

Per i vettori di rotazione (utilizzati nelle app bussola o XR), utilizza SensorManager.remapCoordinateSystem() per mappare la direzione dell'obiettivo della fotocamera o la parte superiore dello schermo ai nuovi assi in base alla rotazione attuale.

Compatibilità con le app

Le applicazioni devono rispettare le norme sulla qualità delle app per garantire la compatibilità con tutti i fattori di forma e i display connessi. Se un'applicazione non può rispettare le linee guida, i produttori di dispositivi possono implementare trattamenti di compatibilità, anche se ciò potrebbe peggiorare l'esperienza utente.

Per ulteriori informazioni, consulta l'elenco completo delle soluzioni alternative per la compatibilità fornite nella piattaforma, in particolare quelle relative all'anteprima della videocamera, agli override e alle modifiche all'API Android 16 che potrebbero modificare il comportamento della tua app.

Per scoprire di più sulla creazione di app adattive, consulta Qualità delle app per schermi di grandi dimensioni.