Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Modalità di compatibilità del dispositivo

Android attiva una modalità di compatibilità per le app che dichiarano limitazioni di orientamento o ridimensionamento. La modalità di compatibilità garantisce un comportamento accettabile dell'app su dispositivi con schermi di grandi dimensioni, flip phone pieghevoli e ambienti desktop, ma con un'usabilità non ottimale.

Gli override per app consentono ai produttori di dispositivi, ai proprietari di dispositivi virtuali¹ e agli utenti di modificare il comportamento delle app per migliorarne il layout o impedire che si interrompano su determinati dispositivi.

Android 16

Android 16 (livello API 36) ignora le limitazioni relative all'orientamento dello schermo, alle proporzioni e alla ridimensionabilità delle app per migliorare il layout delle app sui fattori di forma con larghezza minima >= 600 dp.

I seguenti override per app non sono funzionali per le app che hanno come target il livello API 36:

FORCE_RESIZE_APP
FORCE_NON_RESIZE_APP
OVERRIDE_MIN_ASPECT_RATIO
OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY
OVERRIDE_MIN_ASPECT_RATIO_MEDIUM
OVERRIDE_MIN_ASPECT_RATIO_LARGE
OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN
OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN
OVERRIDE_ANY_ORIENTATION
OVERRIDE_ANY_ORIENTATION_TO_USER
OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE
OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA
OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION
OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED
OVERRIDE_RESPECT_REQUESTED_ORIENTATION

Disattiva

La tua app può avere come target il livello API 36, ma disattivare il comportamento di Android 16. In questo caso, OVERRIDE_ANY_ORIENTATION_TO_USER non è applicabile.

Avviso:

Tutti gli override diversi da OVERRIDE_ANY_ORIENTATION_TO_USER sono applicabili anche se la tua app disattiva il comportamento di Android 16. Pertanto, le limitazioni relative all'orientamento dello schermo, alle proporzioni e alla ridimensionabilità della tua app possono comunque essere sostituite se i produttori di dispositivi hanno implementato gli override.
Gli utenti possono eseguire l'override delle proporzioni dell'app in Impostazioni anche se la tua app disattiva questa opzione. Consulta Override per app dell'utente.
Finestre delle app:
- Le limitazioni di orientamento vengono ignorate nonostante la tua app abbia eseguito l'opt-out.
- Le limitazioni di ridimensionamento vengono rispettate se la tua app disattiva questa funzionalità. Tuttavia, è possibile applicare il ridimensionamento proporzionale.

Dichiara la proprietà manifest

Per disattivare il comportamento del livello API 36, dichiara la proprietà del manifest PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY.

Per disattivare una specifica attività, imposta la proprietà nell'elemento <activity>:

<activity ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</activity>

Per disattivare l'opzione per l'intera app, imposta la proprietà nell'elemento <application>:

<application ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</application>

Se la tua app ha come target Android 16 (livello API 36) o versioni successive, questa proprietà non blocca l'orientamento dello schermo né impedisce la rotazione dello schermo su display di grandi dimensioni.

Dispositivi di riferimento

I seguenti dispositivi potrebbero richiedere override per app a causa di configurazioni insolite o non ben supportate dalle app:

Tablet:l'orientamento naturale di alcuni tablet, come Pixel Tablet, è orizzontale. Un dispositivo è nel suo orientamento naturale quando Display#getRotation() restituisce Surface.ROTATION_0. Se le app presuppongono che ROTATION_0 sia in modalità Ritratto, i layout delle app e l'anteprima della fotocamera potrebbero non corrispondere al display del dispositivo.
Pieghevoli con orientamento orizzontale:alcuni dispositivi pieghevoli, come Pixel Fold, sono in orientamento verticale quando sono piegati, ma in orientamento orizzontale quando sono aperti. Se le app presuppongono che l'orientamento aperto sia verticale, è probabile che si verifichino loop di sfarfallio o problemi di layout.
Flip phone pieghevoli:i flip phone aperti sono in genere in orientamento verticale. Tuttavia, quando sono chiusi, gli smartphone di solito hanno un piccolo display con orientamento orizzontale. Le app devono identificare e adattarsi ai diversi orientamenti dei display.
Display esterni:alcuni dispositivi possono avviare una sessione di finestre delle app su display esterni collegati. Le app devono eseguire query sui display esterni per ottenere informazioni come le dimensioni e la risoluzione dello schermo. In caso contrario, le app potrebbero fare supposizioni errate sui display, il che può portare a un comportamento errato dell'app.
Display per auto:molti display per auto, ma non tutti, sono in orizzontale. Lo sviluppo di app per auto parcheggiate per i display delle auto è simile allo sviluppo per tablet.

Problemi di compatibilità comuni

I problemi di compatibilità dell'esperienza con l'app si verificano più spesso a causa di limitazioni di orientamento, ridimensionamento e proporzioni, gestione errata dell'orientamento dell'anteprima della fotocamera e utilizzo improprio delle API.

Letterboxing

Il letterboxing posiziona l'app al centro dello schermo o, su schermi di grandi dimensioni, su un lato o sull'altro per un accesso comodo. Le barre opache (barre in tinta unita o sfondo sfocato) riempiono l'area del display inutilizzata lungo i lati o nella parte superiore e inferiore dell'app.

Il letterbox si verifica spesso sui dispositivi con schermi grandi perché le dimensioni e le proporzioni del display del dispositivo sono solitamente diverse da quelle degli smartphone standard, per i quali è progettata la maggior parte delle app.

Figura 1. L'app limitata all'orientamento verticale viene visualizzata in formato letterbox su tablet e pieghevoli in orizzontale.

Problema

L'app non supporta tutte le configurazioni di visualizzazione perché ha un orientamento fisso, proporzioni fisse o non è ridimensionabile.

Le impostazioni di configurazione che controllano l'orientamento e la ridimensionabilità dell'app includono:

screenOrientation: specifica un orientamento fisso per un'app. Le app possono anche impostare l'orientamento in fase di runtime utilizzando Activity#setRequestedOrientation().
resizeableActivity: indica se il sistema può ridimensionare le app per adattarle a finestre di dimensioni diverse. Su Android 11 (livello API 30) e versioni precedenti, specifica se le app supportano la modalità multi-finestra. Su Android 12 (livello API 31) e versioni successive, specifica se le app supportano la modalità multi-finestra su schermi di piccole dimensioni (classe di dimensioni della finestra compatta). Su Android 12 e versioni successive, le app supportano la modalità multi-finestra su schermi di grandi dimensioni (classe di dimensioni della finestra media o espansa) indipendentemente da questa impostazione.
maxAspectRatio: Specifica il rapporto di aspetto massimo supportato dall'app. Solo le app conresizeableActivity impostato sufalse può impostaremaxAspectRatio.
minAspectRatio: specifica le proporzioni minime supportate dall'app. Solo le app con resizeableActivity impostato su false possono impostare minAspectRatio.

App limitata all'orientamento verticale non utilizzabile su un dispositivo con orientamento orizzontale.

Ottimizzazione

L'app deve supportare tutti gli orientamenti e le dimensioni di visualizzazione dei dispositivi e della modalità multi-finestra. Rimuovi tutte le limitazioni relative all'orientamento e alle proporzioni fisse dai layout e dal file manifest dell'app.

L'app supporta tutti gli orientamenti del dispositivo.

Soluzione alternativa per la compatibilità

Se un'app con orientamento o proporzioni fisse viene eseguita in una finestra in cui l'app non supporta direttamente le dimensioni o l'orientamento della finestra, Android applica il formato letterbox all'app per preservare la continuità.

A partire da Android 12 (livello API 31) e continuando con 12L (livello API 32), la piattaforma applica una serie di miglioramenti alle app letterbox. I produttori di dispositivi implementano i miglioramenti dell'interfaccia utente. Non è necessario eseguire ulteriori attività di sviluppo per consentire alla tua app di usufruire dei miglioramenti.

Android 12 (livello API 31) introduce i seguenti miglioramenti estetici, che possono essere configurati dai produttori di dispositivi:

Angoli arrotondati:gli angoli della finestra dell'app hanno un aspetto più raffinato.
Trasparenza della barra di sistema:le barre di stato e di navigazione, che si sovrappongono all'app, sono semitrasparenti, in modo che le icone sulle barre siano sempre visibili sullo sfondo del letterbox.
Proporzioni configurabili:le proporzioni dell'app possono essere regolate per migliorarne l'aspetto.

Figura 2. App in formato letterbox con miglioramenti dell'interfaccia utente.

12L (livello API 32) aggiunge i seguenti miglioramenti funzionali:

Posizionamento configurabile:sui display di grandi dimensioni, i produttori di dispositivi possono posizionare l'app sul lato sinistro o destro dello schermo, semplificando l'interazione.
Pulsante di riavvio riprogettato:i produttori di dispositivi possono dare al pulsante di riavvio per la modalità di compatibilità delle dimensioni un nuovo aspetto per un migliore riconoscimento da parte degli utenti.

Android 13 (livello API 33) aggiunge una finestra di dialogo di formazione per l'utente sul posizionamento dell'app letterbox sullo schermo o sull'inclusione del letterbox in modalità schermo diviso:

Figura 3. App con formato letterbox con finestra di dialogo di formazione per l'utente.

Modalità di compatibilità delle dimensioni

La modalità di compatibilità delle dimensioni è il letterbox che mantiene le proporzioni dell'app e include un controllo di riavvio. Il controllo consente agli utenti di riavviare l'app e ridisegnare il display. Android richiama la modalità di compatibilità delle dimensioni per le app che non sono ridimensionabili. Quando un'attività viene spostata in un container di visualizzazione non compatibile con le sue dimensioni, il sistema potrebbe ridimensionare l'app per riempire il display del dispositivo in almeno una dimensione.

Le modifiche alla configurazione del dispositivo che possono attivare la modalità di compatibilità delle dimensioni includono:

Rotazione del dispositivo
Dispositivo pieghevole che viene aperto o chiuso
Passare dalla modalità di visualizzazione a schermo intero a quella a schermo diviso e viceversa

Problema

La modalità di compatibilità delle dimensioni si applica in genere alle attività con orientamento o proporzioni limitati e configurate (o determinate dal sistema) in modo da non essere ridimensionabili.

La tua app è considerata ridimensionabile e non verrà inserita nella modalità di compatibilità delle dimensioni se soddisfa uno dei seguenti criteri:

È ridimensionabile con resizeableActivity="true"
Supporta la modalità Picture in picture (PIP)
È incorporato
È stato applicato l'override per app FORCE_RESIZE_APP dal produttore del dispositivo (le proprietà impostate dall'app vengono ignorate)

Se la tua app non soddisfa nessuna delle condizioni, viene considerata non ridimensionabile e potrebbe essere attivata la modalità di compatibilità delle dimensioni.

L'app non ridimensionabile si arresta in modo anomalo in modalità multi-finestra.

Ottimizzazione

L'app deve supportare tutte le dimensioni di visualizzazione. Rendi la tua app ridimensionabile impostando l'attributo android:resizeableActivity dell'elemento <activity> o <application> su true nel manifest dell'app. Progetta layout adattabili/responsive per la tua app. Per maggiori informazioni, consulta Supporta diverse dimensioni di display e Supporta la modalità multi-finestra.

L'app funziona con tutte le dimensioni della finestra.

Soluzione alternativa per la compatibilità

Android attiva la modalità di compatibilità delle dimensioni di un'app quando il sistema determina che la visualizzazione dell'app con letterbox può essere migliorata ridimensionando l'app in modo che riempia la finestra di visualizzazione in almeno una dimensione. Il sistema visualizza un controllo di riavvio che ricrea il processo dell'app, ricreando l'attività e ridisegnando il display. Consulta anche la panoramica di processi e thread.

App solo in modalità verticale con formato letterbox in orientamento orizzontale, ridimensionata dal controllo di riavvio.

Modalità di compatibilità del display

La modalità di compatibilità del display impedisce il riavvio di un'app quando questa si sposta tra display diversi, il che può attivare una modifica della configurazione, ad esempio una modifica della modalità colore, della disponibilità del touchscreen o della densità dello schermo.

La modalità di compatibilità del display è attiva per impostazione predefinita per i giochi (in base al flag android:appCategory) per migliorare la stabilità e la continuità. A differenza della modalità di compatibilità delle dimensioni, la modalità di compatibilità di visualizzazione non blocca la configurazione dell'app. L'app può comunque ricevere tutti gli aggiornamenti della configurazione tramite API come il callback onConfigurationChanged(), ma viene risparmiato un riavvio invasivo. Ciò significa che i giochi che supportano correttamente API come onConfigurationChanged() possono comunque aggiornare la propria UI in modo adattabile anche se sono in modalità di compatibilità del display.

Per disattivare la modalità di compatibilità del display e gestire le modifiche alla configurazione nella tua app, dichiara il supporto per le modifiche alla configurazione nel file AndroidManifest.xml dell'app e gestisci le modifiche alla configurazione nel callback onConfigurationChanged().

<activity
    android:name=".MyGameActivity"
    android:configChanges="colorMode|touchscreen|density|...">
    ...
</activity>

Loop tremolanti

Quando un'app non supporta tutti gli orientamenti del display, potrebbe richiedere ripetutamente nuovi orientamenti quando si verifica una modifica della configurazione, creando un loop infinito che fa sfarfallare il display o ruotare l'app all'infinito.

Problema

Su Android 12 (livello API 31) e versioni successive, i produttori di dispositivi possono configurare i propri dispositivi in modo che ignorino le limitazioni di orientamento specificate dalle app e applicare invece le modalità di compatibilità. Ad esempio, un dispositivo pieghevole potrebbe ignorare l'impostazione android:screenOrientation="portrait" di un'attività quando questa viene visualizzata sullo schermo interno del dispositivo, di dimensioni simili a quelle di un tablet in modalità Orizzontale.

Se le limitazioni di orientamento di un'app vengono ignorate, l'app può impostare l'orientamento in modo programmatico chiamando Activity#setRequestedOrientation(). La chiamata attiva un riavvio dell'app se quest'ultima non gestisce le modifiche alla configurazione (consulta Gestisci le modifiche alla configurazione). Dopo il riavvio, le limitazioni di orientamento dell'app vengono nuovamente ignorate, l'app ripete la chiamata a setRequestedOrientation(), la chiamata attiva un riavvio dell'app e così via in un loop che si perpetua.

Un altro modo in cui potresti riscontrare questo problema è quando l'orientamento naturale (l'orientamento consueto determinato da Android) dello schermo di un dispositivo è orizzontale (ovvero, la chiamata a Display#getRotation() restituisce Surface.ROTATION_0 mentre il dispositivo ha un formato orizzontale). In passato, le app presupponevano che Display.getRotation() = Surface.ROTATION_0 significasse che il dispositivo era in orientamento verticale, ma non è sempre così, ad esempio sullo schermo interno di alcuni dispositivi pieghevoli e su alcuni tablet.

Un'app con orientamento orizzontale su un display interno pieghevole potrebbe controllare la rotazione dello schermo, ricevere un valore di ROTATION_0, presumere che l'orientamento naturale del dispositivo sia verticale e chiamare setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT ) per riconfigurare il layout dell'app. Dopo il riavvio dell'app (in orientamento orizzontale), potrebbe controllare di nuovo la rotazione dello schermo, ricevere un valore di ROTATION_0, chiamare setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT) e continuare il loop infinito.

L'app solo orizzontale sul display verticale effettua chiamate ripetute a `Activity#setRequestedOrientation()`.

Ottimizzazione

Le app non devono:

Imposta un orientamento predefinito con Activity#setRequestedOrientation() nel metodo onCreate() dell'attività, perché la richiesta di orientamento può essere attivata in modo imprevisto da modifiche alla configurazione non gestite
Presupponi che l'orientamento naturale del dispositivo (ROTATION_0) sia verticale
Imposta l'orientamento in base a indicatori non correlati alle dimensioni della finestra corrente, ad esempio Display#getRotation(), presenza di un FoldingFeature o API deprecate.

L'app gestisce la modifica della configurazione, non ha limitazioni di orientamento, quindi non entra in un loop di sfarfallio.

Soluzione alternativa per la compatibilità

Android ignora le chiamate a Activity#setRequestedOrientation() nelle seguenti situazioni:

L'attività è già stata rilanciata da una chiamata precedente al metodo o è stato attivato il trattamento di rotazione forzata della compatibilità della fotocamera (vedi Anteprima della fotocamera di seguito).

I produttori di dispositivi possono applicare questo comportamento a un'app con OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION.
L'attività ha effettuato più di due richieste di orientamento in un secondo, il che indica che si è verificato un loop. Delle due richieste nel loop, Android utilizza quella che massimizza l'area di visualizzazione dell'app.

I produttori di dispositivi possono applicare questo comportamento a un'app con OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED.
I proprietari dei dispositivi virtuali hanno eseguito l'override della chiamata al metodo su dispositivi selezionati.

Anteprima fotocamera

L'anteprima della fotocamera (o il mirino) delle app della fotocamera può essere disallineata o distorta su tablet, laptop e display pieghevoli.

Consulta anche Anteprima della fotocamera in finestre delle app.

Problema

Il documento di definizione della compatibilità di Android stabilisce che un sensore di immagine della fotocamera "DEVE essere orientato in modo che la dimensione lunga della fotocamera sia allineata alla dimensione lunga dello schermo".

Le app spesso presuppongono che l'orientamento del dispositivo e quello del sensore della fotocamera siano verticali, un'ipotesi ragionevole sugli smartphone standard. Tuttavia, l'orientamento naturale di tablet e laptop e dei relativi sensori della fotocamera può essere orizzontale. Inoltre, i nuovi fattori di forma, come i pieghevoli, possono avere più orientamenti naturali e più sensori della fotocamera con orientamenti diversi.

L'avvio di un'attività con un orientamento della fotocamera non previsto dall'app o il passaggio da una fotocamera all'altra o da uno schermo all'altro (per i pieghevoli) può causare un'anteprima della fotocamera non allineata o distorta.

Anteprima della fotocamera disallineata e distorta su un dispositivo pieghevole con schermo grande.

Ottimizzazione

Le app per fotocamera devono identificare e gestire correttamente l'orientamento del dispositivo e del sensore della fotocamera per presentare un'anteprima della fotocamera allineata e ridimensionata correttamente. Le app devono calcolare la rotazione del dispositivo, la rotazione del sensore e le proporzioni dello schermo o della finestra, quindi applicare i risultati all'anteprima della fotocamera. Per indicazioni dettagliate, consulta Anteprima fotocamera e Introduzione al mirino della fotocamera.

Anteprima della fotocamera allineata e ridimensionata correttamente in tutti gli orientamenti del dispositivo.

Soluzione alternativa per la compatibilità

Un dispositivo è in orientamento naturale quando Display#getRotation() restituisce Surface.ROTATION_0. Il sistema calcola CameraCharacteristics.SENSOR_ORIENTATION dall'orientamento naturale del dispositivo. Android allinea la finestra verticale delle app con limitazioni di orientamento verticale all'orientamento naturale del dispositivo, che è quello previsto dalla maggior parte delle app. Android ritaglia anche l'immagine del sensore della fotocamera quando l'orientamento del sensore è orizzontale e l'anteprima della fotocamera è verticale. Le soluzioni alternative specifiche includono:

Forza la rotazione delle anteprime della fotocamera per le app con orientamento verticale limitato:le app con orientamento verticale limitato prevedono che l'orientamento naturale del dispositivo e l'orientamento del sensore della fotocamera siano verticali. Tuttavia, su Android 12 (livello API 31) e versioni successive, le app possono essere eseguite in più orientamenti del dispositivo se i produttori di dispositivi ignorano la specifica dell'orientamento.

Quando un'app con limitazioni per la modalità Ritratto è connessa alla fotocamera, Android forza la rotazione dell'app per allineare la finestra dell'app in modalità Ritratto con l'orientamento naturale del dispositivo.

Su alcuni tablet (vedi dispositivi di riferimento), la finestra verticale dell'app viene ruotata in modalità verticale a schermo intero per allinearsi all'orientamento naturale del dispositivo. L'app occupa l'intero schermo dopo la rotazione forzata.

Tablet: forza la rotazione dell'app con orientamento verticale limitato.

Sullo schermo interno orizzontale dei pieghevoli (vedi dispositivi di riferimento), le attività solo in verticale vengono ruotate in orizzontale per allinearsi all'orientamento naturale aperto. L'app è in formato letterbox dopo la rotazione forzata.

Pieghevole: rotazione forzata dell'app con limitazione alla modalità Ritratto. L'app è anche in formato letterbox.

Nota: la rotazione forzata non avviene se l'app è adattabile e gestisce gli orientamenti verticale e orizzontale.
Ritaglio della fotocamera anteriore interna:il sensore della fotocamera anteriore interna di alcuni pieghevoli è in orientamento orizzontale. Oltre a forzare la rotazione dell'anteprima della fotocamera sul display interno pieghevole, Android ritaglia il campo visivo della fotocamera anteriore interna (orizzontale) in modo che il sensore acquisisca una visuale opposta all'orientamento del dispositivo.
Forza l'aggiornamento delle anteprime della fotocamera:il sistema passa in rassegna i metodi di attività onStop() e onStart() (per impostazione predefinita) o onPause() e onResume() (applicati dall'override per app OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE) dopo la rotazione forzata per assicurarsi che l'anteprima della fotocamera venga visualizzata correttamente.
Scalabilità delle proporzioni:il sistema modifica dinamicamente le proporzioni dell'anteprima della fotocamera con rotazione forzata impostandole su proporzioni minime più elevate, il che garantisce che l'anteprima della fotocamera venga ridimensionata correttamente.

Gli sviluppatori di app possono eseguire l'override di queste soluzioni alternative se le app gestiscono correttamente l'anteprima della fotocamera. Consulta Override per app.

API comunemente utilizzate in modo improprio

Poiché Android ha aggiunto il supporto di funzionalità come la modalità multi-finestra e di dispositivi come i pieghevoli, le API legacy sono state ritirate e sostituite da API aggiornate che funzionano per tutte le dimensioni di display e i form factor dei dispositivi. Tuttavia, le API ritirate sono ancora disponibili per la compatibilità con le versioni precedenti.

Alcune API View sono progettate per scopi speciali che non sono sempre ben compresi dagli sviluppatori.

Problema

Gli sviluppatori continuano a utilizzare le API Display deprecate e presumono erroneamente che le API restituiscano i limiti dell'app anziché i limiti dell'area di visualizzazione del dispositivo. In alternativa, gli sviluppatori utilizzano erroneamente API di visualizzazione per scopi speciali per ottenere metriche di visualizzazione generali. Il risultato sono errori di calcolo durante il riposizionamento degli elementi UI dopo gli eventi di ridimensionamento della finestra dell'app, che causano problemi di layout.

API Display deprecate e comunemente utilizzate in modo errato:

Per saperne di più, consulta Supporta la modalità multi-finestra.

API di visualizzazione utilizzate in modo improprio:

L'API deprecata calcola in modo errato i limiti dell'app. I contenuti dell'app escono dallo schermo.

Ottimizzazione

Non fare mai affidamento sulle dimensioni fisiche del display per il posizionamento degli elementi UI. Esegui la migrazione della tua app alle API basate su WindowMetrics, incluse le seguenti API WindowManager:

Piattaforma:
- getCurrentWindowMetrics()
- getMaximumWindowMetrics()
Jetpack:
- WindowMetricsCalculator#computeCurrentWindowMetrics()
- WindowMetricsCalculator#computeMaximumWindowMetrics()

L'API calcola correttamente le metriche della finestra dell'app.

Soluzione alternativa per la compatibilità

Due override regolano le API Display ritirate e le API View utilizzate in modo improprio per restituire i limiti dell'app: ALWAYS_SANDBOX_DISPLAY_APIS per le API Display; OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS per le API View. ALWAYS_SANDBOX_DISPLAY_APIS viene applicato per impostazione predefinita anche alle app idonee per la modalità di compatibilità delle dimensioni.

Attività trasparenti

Le attività trasparenti sono il risultato di stili di sfondo trasparenti, ad esempio:

<style name="Transparent" parent="AppTheme">
    <item name="android:windowIsTranslucent">true</item>
    <item name="android:windowBackground">@android:color/transparent</item>
</style>

I temi relativi alle finestre di dialogo, come Theme.MaterialComponents.Dialog, possono includere stili che rendono trasparenti le attività.

Le attività trasparenti non coprono tutto lo spazio di visualizzazione disponibile, il che le rende difficili da gestire perché l'area di visualizzazione disponibile può cambiare in base alle modifiche alla configurazione, come la rotazione del dispositivo, l'apertura e la chiusura del dispositivo e la modalità multi-finestra.

Problema

Un'attività trasparente deve essere conforme ai limiti della prima attività opaca sotto l'attività trasparente nello stack delle attività. Tuttavia, un'attività opaca che avvia una finestra di dialogo per le autorizzazioni può essere un trampolino (un'attività che avvia un'altra attività e poi scompare). Di conseguenza, il sistema non può determinare i limiti dell'attività trampolino che ha avviato l'attività della finestra di dialogo per le autorizzazioni trasparente.

Finestra di dialogo posizionata in modo errato perché l'attività è stata avviata da un trampolino.

Ottimizzazione

Le attività trasparenti ereditano i vincoli dall'attività opaca più in alto sotto di loro nello stack delle attività di un'attività. L'attività opaca deve essere disponibile per l'intero ciclo di vita dell'attività trasparente, dalla creazione alla distruzione dell'attività. Per questo motivo, non lanciare richieste di autorizzazione da attività trampoline.

Se un'attività trampoline avvia una richiesta di autorizzazione, l'utente potrebbe non essere in grado di visualizzare la finestra di dialogo di autorizzazione perché l'attività trampoline verrà eliminata prima che l'utente abbia avuto la possibilità di rispondere alla finestra di dialogo e le dimensioni e la posizione dell'attività della finestra di dialogo potrebbero essere state calcolate in modo errato.

Le app devono sempre avviare le richieste di autorizzazione da attività che rimangono visibili finché l'utente non ha preso una decisione in merito all'autorizzazione.

Angoli arrotondati

Un'attività può essere trasparente a causa di uno stile che specifica la trasparenza dello sfondo o perché i contenuti dell'attività non riempiono lo spazio di visualizzazione disponibile. Se un'attività trasparente riempie lo spazio di visualizzazione disponibile, il sistema applica automaticamente gli angoli arrotondati all'attività, se configurato in questo modo dal produttore del dispositivo. Tuttavia, se un'attività trasparente (come una finestra di dialogo per le autorizzazioni) non riempie lo spazio disponibile, spetta a te decidere se applicare o meno gli angoli arrotondati.

Le finestre di dialogo delle autorizzazioni non riempiono lo spazio di visualizzazione disponibile perché il layout della finestra di dialogo utilizza in genere LayoutParams.WRAP_CONTENT anziché LayoutParams.MATCH_PARENT.

Finestra di dialogo con angoli arrotondati posizionata correttamente sopra l'attività di avvio visibile.

Soluzione alternativa per la compatibilità

Mantieni visibili le attività che avviano attività di dialogo finché l'utente non ha risposto alla finestra di dialogo.

Il sistema garantisce che un'attività trasparente erediti tutti i vincoli dalla prima attività opaca sotto l'attività trasparente nello stack delle attività, inclusi i vincoli relativi a:

Modalità di compatibilità delle dimensioni
Orientamento
Proporzioni

Giochi Unity

I giochi Unity vengono eseguiti su Android a schermo intero o in modalità multi-finestra. Tuttavia, molti giochi Unity perdono lo stato attivo e smettono di mostrare i contenuti quando l'app viene attivata in modalità multi-finestra.

Problema

Unity ha aggiunto un'opzione Resizable Window in Unity 2019.4 per supportare la modalità multi-finestra su Android. Tuttavia, l'implementazione iniziale non ha reagito correttamente al ciclo di vita dell'attività in modalità multi-finestra, causando la sospensione della riproduzione da parte di UnityPlayer quando l'app perde lo stato attivo. Il player ha mostrato una schermata nera o l'ultimo frame bloccato del gioco. Il gameplay riprendeva solo quando l'utente toccava lo schermo. Molte app che utilizzano il motore Unity riscontrano questo problema e vengono visualizzate come una finestra nera in modalità multi-finestra.

Il gioco perde lo stato attivo in modalità multi-finestra e viene visualizzato come una finestra nera.

Ottimizzazione

Esegui l'upgrade di Unity alla versione 2019.4.40 o successive ed esporta di nuovo il gioco. Mantieni selezionata l'opzione Resizable Window nelle impostazioni di Android Player, altrimenti il gioco viene messo in pausa quando non è attivo, anche se è completamente visibile in modalità multi-finestra.

Il gioco esegue il rendering dei contenuti correttamente in modalità multi-finestra anche quando non è attivo.

Soluzione alternativa per la compatibilità

I produttori di dispositivi possono applicare l'override per app OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS per fornire un evento di stato attivo fittizio a un'app in modalità multi-finestra. L'override consente all'attività di ridisegnare i contenuti e di non essere oscurata.

Finestre delle app

Quando le app vengono eseguite in un ambiente con finestre delle app, potrebbero riscontrare modalità di compatibilità aggiuntive.

Le app con orientamento bloccato possono essere ridimensionate liberamente. Anche se un'attività è bloccata sull'orientamento verticale, gli utenti possono comunque ridimensionare l'app in orientamento orizzontale.

Animazione di un'app in modalità verticale che viene ridimensionata in modalità orizzontale.

Le app con orientamento bloccato possono comunque essere ridimensionate liberamente.

Tuttavia, se un'attività viene dichiarata come non ridimensionabile (resizeableActivity = false), l'UI dell'attività viene scalata mantenendo lo stesso formato.

Animazione del ridimensionamento dell'app. La UI si adatta alla finestra del desktop.

L'UI delle attività dichiarate come non ridimensionabili viene scalata.

Anteprima della fotocamera in modalità finestre delle app

Quando un'app viene eseguita in modalità finestre delle app, la rotazione del display e l'orientamento della finestra possono essere diversi da quelli che potrebbero verificarsi in modalità a schermo intero sugli smartphone standard.

Problema

Le app spesso presuppongono che l'orientamento del dispositivo e quello del sensore della fotocamera siano verticali, il che può comportare un'anteprima della fotocamera non allineata o distorta.

Ottimizzazione

Le app per fotocamera devono identificare e gestire correttamente l'orientamento del dispositivo e del sensore della fotocamera per presentare un'anteprima della fotocamera allineata e ridimensionata correttamente. Le app devono calcolare la rotazione del dispositivo, la rotazione del sensore e le proporzioni della finestra, quindi applicare i risultati all'anteprima della fotocamera, che deve anche rispondere alle modifiche alla configurazione della finestra. Per indicazioni dettagliate, consulta Anteprima della videocamera.

Soluzione alternativa per la compatibilità

Quando le app con orientamento fisso in finestre delle app avviano un'anteprima della fotocamera, il sistema potrebbe attivare il trattamento di compatibilità della fotocamera per evitare anteprime allungate e laterali.

Il trattamento isola l'ambiente in modo che corrisponda all'orientamento richiesto nei seguenti modi:

Visualizza la finestra dell'app in formato letterbox nell'orientamento richiesto:in questo modo eviti problemi di allungamento dovuti a una scalabilità inappropriata.
Sandbox della rotazione del display:il trattamento simula il dispositivo posizionato nell'orientamento richiesto. Poiché l'ipotesi errata più comune per le anteprime della fotocamera è che l'app sia in esecuzione su un dispositivo con orientamento verticale, la rotazione del display è limitata a 0 gradi per le app che richiedono l'orientamento verticale e a 90 gradi per i dispositivi che richiedono l'orientamento orizzontale.
Ritaglio della fotocamera: se la rotazione del display è cambiata, questo si riflette sul feed videocamera: se un dispositivo è in orientamento orizzontale e il trattamento viene attivato per un'app che richiede l'orientamento verticale, il campo visivo della fotocamera viene ritagliato in modo da assomigliare a quello di una fotocamera con orientamento verticale.
Ruota e ritaglia il feed videocamera:il sistema passa in rassegna i metodi di attività onStop() e onStart() (per impostazione predefinita) o onPause() e onResume() (applicati dall'override per app OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE) dopo l'applicazione del trattamento per assicurarsi che l'anteprima della fotocamera venga visualizzata correttamente.

Gli sviluppatori di app possono eseguire l'override di queste soluzioni alternative se le app gestiscono correttamente l'anteprima della fotocamera. Consulta Override per app.

Ridimensionamento

Quando è attivo un trattamento di orientamento richiesto simulato, il ridimensionamento della finestra scala l'UI del mirino mantenendo le proporzioni. Il resto della finestra dell'app può essere ridimensionato liberamente.

Ridimensionamento di una finestra con il mirino della fotocamera

Testa la tua app per individuare eventuali problemi di compatibilità

Per testare la tua app e capire come si comporta su diversi fattori di forma, sfrutta le seguenti risorse:

Streaming dei dispositivi:per testare la tua app su dispositivi di produzione (inclusi i dispositivi di riferimento) ospitati nei data center di Google, consulta Android Device Streaming, basato su Firebase .
Emulatori in Android Studio: per informazioni sulla creazione di emulatori per i dispositivi di riferimento, consulta Crea e gestisci i dispositivi virtuali.
Emulatore ridimensionabile di Android Studio:per informazioni sull'accesso ai dispositivi virtuali, consulta Esegui app sull'emulatore Android

È in formato letterbox

Verifica che ogni attività possa utilizzare tutto lo spazio di visualizzazione disponibile per l'app. Innanzitutto, dichiara il seguente codice nella cartella di test:

Kotlin

fun isLetterboxed(activity: AppCompatActivity): Boolean {
    if (isInMultiWindowMode) return false

    val wmc = WindowMetricsCalculator.getOrCreate()
    val currentBounds = wmc.computeCurrentWindowMetrics(this).bounds
    val maxBounds = wmc.computeMaximumWindowMetrics(this).bounds

    val isScreenPortrait = maxBounds.height() > maxBounds.width()

    return if (isScreenPortrait) {
        currentBounds.height() < maxBounds.height()
    } else {
        currentBounds.width() < maxBounds.width()
    }
}DeviceCompatibilityModeKotlinSnippets.kt

Java

public boolean isLetterboxed(AppCompatActivity activity) {
    if (activity.isInMultiWindowMode()) {
        return false;
    }

    WindowMetricsCalculator wmc = WindowMetricsCalculator.getOrCreate();
    Rect currentBounds = wmc.computeCurrentWindowMetrics(activity).getBounds();
    Rect maxBounds = wmc.computeMaximumWindowMetrics(activity).getBounds();

    boolean isScreenPortrait = maxBounds.height() > maxBounds.width();

    return (isScreenPortrait)
        ? currentBounds.height() < maxBounds.height()
        : currentBounds.width() < maxBounds.width();
}DeviceCompatibilityModeJavaSnippets.java

Quindi esegui un test per verificare il comportamento e assicurarti che l'attività di destinazione non sia in formato letterbox:

Kotlin

@get:Rule
val activityRule = ActivityScenarioRule(MainActivity::class.java)

@Test
fun activity_launched_notLetterBoxed() {
    activityRule.scenario.onActivity {
        assertFalse(it.isLetterboxed())
    }
}DeviceCompatibilityModeTestKotlinSnippets.kt

Java

@Rule
public ActivityScenarioRule<MainActivity> rule = new ActivityScenarioRule<>(MainActivity.class);

@Test
public void activity_launched_notLetterBoxed() {
    try (ActivityScenario<MainActivity> scenario =
        ActivityScenario.launch(MainActivity.class)) {
            scenario.onActivity( activity -> {
                assertFalse(activity.isLetterboxed());
            });
        }
}DeviceCompatibilityModeTestJavaSnippets.java

Idealmente, esegui questo tipo di test solo fino a quando non viene superato e conferma che le attività della tua app occupano l'intero spazio di visualizzazione disponibile per l'app. Testa la tua app su tutti i tipi di dispositivi per garantire un comportamento coerente.

Override per app

Android fornisce override che modificano il comportamento configurato delle app. Ad esempio, l'override FORCE_RESIZE_APP indica al sistema di ignorare la modalità di compatibilità delle dimensioni e di ridimensionare l'app in modo che si adatti alle dimensioni del display anche se nel manifest dell'app è specificato resizeableActivity="false".

I produttori di dispositivi applicano gli override a determinate app o a tutte le app su dispositivi specifici. Su Android 14 (livello API 34) e versioni successive, gli utenti possono applicare override alle app tramite le impostazioni del dispositivo. Su Android 16 (livello API 36) e versioni successive, i proprietari di dispositivi virtuali applicano gli override su dispositivi selezionati che gestiscono.

Override per app dell'utente

Su Android 14 e versioni successive, un menu delle impostazioni consente agli utenti di modificare le proporzioni delle app. I dispositivi con schermo grande, come i dispositivi di riferimento, implementano il menu.

Il menu contiene un elenco di tutte le app installate sul dispositivo. Gli utenti scelgono un'app e poi impostano le proporzioni dell'app su 3:4, 1:1, schermo intero o un altro valore configurato dal produttore del dispositivo. Gli utenti possono anche reimpostare le proporzioni predefinite dell'app, specificate nel manifest dell'app.

Le app possono disattivare l'override di compatibilità impostando i seguenti tag PackageManager.Property:

PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE

Per disattivare l'override della compatibilità con le proporzioni dell'utente, aggiungi la proprietà al manifest dell'app e imposta il valore su false:
```
<application>
    <property
        android:name="android.window.
        PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE"
        android:value="false" />
</application>
```
La tua app verrà esclusa dall'elenco delle app nelle impostazioni del dispositivo. Gli utenti non potranno eseguire l'override delle proporzioni dell'app.

L'impostazione della proprietà su true non ha alcun effetto.
PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE

Per disattivare l'opzione a schermo intero dell'override della compatibilità delle proporzioni utente, aggiungi la proprietà al manifest dell'app e imposta il valore su false:
```
<application>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE"
        android:value="false" />
</application>
```
L'opzione a schermo intero viene rimossa dall'elenco delle opzioni di proporzioni nelle impostazioni del dispositivo. Gli utenti non potranno applicare l'override a schermo intero alla tua app.

Attenzione: se PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE è false, questa proprietà non ha alcun effetto.

L'impostazione di questa proprietà su true non ha alcun effetto.

Ottimizza l'app per tutti gli schermi:non impostare limitazioni relative alle proporzioni nell'app. Utilizza le classi di dimensioni delle finestre per supportare layout diversi in base allo spazio di visualizzazione disponibile.

Override per app del dispositivo

I produttori di dispositivi e i proprietari di dispositivi virtuali (seleziona app attendibili e con privilegi) applicano gli override per app su dispositivi specifici, tra cui tablet, pieghevoli, dispositivi ChromeOS e display per auto. I dispositivi di riferimento potrebbero applicare alcuni degli override a una serie di app per impostazione predefinita.

Le app possono disattivare la maggior parte degli override (consulta la tabella Override per app di seguito).

Puoi testare la tua app con gli override attivati o disattivati utilizzando il framework di compatibilità (consulta Strumenti del framework di compatibilità). Se attivati, gli override vengono applicati all'intera app.

Puoi anche utilizzare Android Debug Bridge (adb) per attivare o disattivare gli override e determinare quali override si applicano alla tua app.

Attiva o disattiva gli override nel seguente modo:

adb shell am compat enable/disable <override name/id> <package>

Per i dispositivi di riferimento, controlla quali override si applicano alla tua app:

adb shell dumpsys platform_compat | grep <package name>

La tabella seguente elenca gli override disponibili, insieme alle indicazioni su come ottimizzare l'app in modo che non debba fare affidamento sugli override. Puoi aggiungere flag di proprietà al manifest dell'app per disattivare alcuni override.

Override per app
Tipo	Nome	ID	Descrizione
Compatibilità input	OVERRIDE_MOUSE_TO_TOUCH	413207127	Converte le istanze `MotionEvent` da un mouse in eventi touch riscrivendo l'origine `MotionEvent` e il tipo di strumento quando vengono inviati all'applicazione.
Ridimensionabilità	FORCE_RESIZE_APP	174042936	Ignora la modalità di compatibilità delle dimensioni per l'app in caso di modifiche alla configurazione.
	FORCE_NON_RESIZE_APP	181136395	Forza l'app in modalità di compatibilità delle dimensioni in caso di modifiche alla configurazione.
Proporzioni	OVERRIDE_MIN_ASPECT_RATIO	174042980	Override del gatekeeper che deve essere abilitato per applicare qualsiasi altro override delle proporzioni.
	OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY	203647190	Se l'opzione è attiva (impostazione predefinita), l'ambito di override è limitato alle attività solo in modalità Ritratto.
	OVERRIDE_MIN_ASPECT_RATIO_SMALL	349045028	Modifica le proporzioni minime in 4:3.
	OVERRIDE_MIN_ASPECT_RATIO_MEDIUM	180326845	Modifica le proporzioni minime in 3:2.
	OVERRIDE_MIN_ASPECT_RATIO_LARGE	180326787	Modifica le proporzioni minime in 16:9.
	OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN	208648326	Modifica le proporzioni minime per adattarle al 50% delle dimensioni del display (o alle proporzioni dello schermo diviso).
	OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN	218959984	Disattiva l'override delle proporzioni minime in modo che le app vengano visualizzate a schermo intero quando il dispositivo è in modalità verticale.
Orientamento	OVERRIDE_ANY_ORIENTATION	265464455	Consente di eseguire l'override di qualsiasi orientamento.
	OVERRIDE_ANY_ORIENTATION_TO_USER	310816437	Esegue l'override delle limitazioni di orientamento, ridimensionamento e proporzioni.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT	265452344	Esegue l'override dell'orientamento in verticale quando un'attività ha un orientamento non definito.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	Esegue l'override dell'orientamento in modo che sia `nosensor` (utilizza l'orientamento naturale del dispositivo) quando un'attività ha un orientamento non definito.
	OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE	266124927	Ruota di 180 gradi le app solo in orizzontale.
	OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA	265456536	Limita l'ambito dell'override dell'orientamento a quando l'app è connessa alla fotocamera.
	OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION	255940284	Imposta il display sull'orientamento naturale orizzontale fisso quando un'attività è a schermo intero (anche in formato letterbox).
	OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION	254631730	Ignora le richieste di orientamento dell'app per evitare loop infiniti di rotazione.
	OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED	273509367	Ignora le richieste di orientamento ripetute durante il riavvio di un'attività. Se Android rileva che un'app richiede almeno due nuovi orientamenti entro un secondo, il sistema considera questa situazione un loop infinito di rotazione e applica l'override.
	OVERRIDE_RESPECT_REQUESTED_ORIENTATION	236283604	Impedisce il letterboxing disattivando l'impostazione del produttore del dispositivo che ignora la richiesta di orientamento.
API Sandbox	NEVER_SANDBOX_DISPLAY_APIS	184838306	Impedisce la modifica del comportamento di qualsiasi API di visualizzazione.
	ALWAYS_SANDBOX_DISPLAY_APIS	185004937	Forza le API `Display` nell'app a restituire i limiti dell'app. Le API `Display` restituiscono i limiti dell'area di visualizzazione logica, ma a volte l'app presuppone che le API `Display` restituiscano i limiti dell'app, il che causa problemi di UI.
	OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS	237531167	Forza le API `View` utilizzate nell'app a restituire i limiti dell'app. Le API `View` restituiscono i limiti dell'area di visualizzazione logica, ma a volte l'app presuppone che le API `View` restituiscano i limiti dell'app, il che causa problemi di UI.
Compatibilità della fotocamera	OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION	263959004	Disattiva la rotazione forzata. Per impostazione predefinita, tutte le app della fotocamera con orientamento fisso vengono ruotate forzatamente quando l'anteprima della fotocamera è aperta.
	OVERRIDE_CAMERA_COMPAT_DISABLE_SIMULATE_REQUESTED_ORIENTATION	398195815	Disattiva la simulazione del trattamento dell'orientamento richiesto per la compatibilità della fotocamera. Per impostazione predefinita, le app della fotocamera con orientamento fisso vengono regolate in base all'orientamento richiesto quando l'anteprima della fotocamera è aperta.
	OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH	264304459	Rimuove l'aggiornamento forzato predefinito applicato quando l'anteprima della fotocamera viene ruotata forzatamente.
	OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE	264301586	Cambia l'aggiornamento forzato in un aggiornamento soft quando l'anteprima della fotocamera viene ruotata forzatamente, il che aiuta a preservare lo stato durante la rotazione forzata. Per impostazione predefinita, Android applica un aggiornamento completo quando l'anteprima della fotocamera viene ruotata forzatamente. L'aggiornamento forzato può causare problemi con le app che perdono lo stato o si oscurano a seconda di come hanno memorizzato nella cache lo stato precedente.
	OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT	250678880	Ritaglia il buffer di immagini della fotocamera anteriore interna. Se l'override è disattivato, il ritaglio della fotocamera anteriore interna viene rimosso e il campo visivo dell'anteprima della fotocamera viene aumentato. Per impostazione predefinita, su alcuni pieghevoli (vedi i dispositivi di riferimento), il sistema ritaglia l'anteprima della fotocamera di tutte le app della fotocamera quando si utilizza la fotocamera anteriore interna.
Varie	OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS	263259275	Impedisce l'oscuramento dell'app quando questa perde lo stato attivo in modalità schermo diviso. L'app attende lo stato attivo prima di disegnare i contenuti dell'app, il che può causare il blocco o l'oscuramento dell'app. L'override consente ad Android di inviare un evento di stato attivo fittizio all'app, che segnala all'app di ricominciare a disegnare i contenuti.
	OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS	388014743	Esclude gli inset della barra dei sottotitoli codificati dai limiti dell'app nella configurazione dell'attività in finestre delle app, impedendo che gli elementi UI dell'app in alto o in basso vengano nascosti dalla barra dei sottotitoli codificati o ritagliati quando l'app non gestisce gli inset della barra dei sottotitoli codificati.

OVERRIDE_MOUSE_TO_TOUCH

Attiva il trattamento di compatibilità che converte le istanze MotionEvent da un mouse o un touchpad in eventi touch riscrivendo l'origine MotionEvent in SOURCE_TOUCHSCREEN e il tipo di strumento MotionEvent in TOOL_TYPE_FINGER quando gli eventi di movimento vengono inviati all'applicazione.

In che modo le app possono ottenere lo stesso risultato dell'override

Non applicabile. Il problema deve essere risolto nella logica dell'applicazione.

Come ottimizzare le app

La tua app deve gestire gli eventi di input da mouse e touchpad, inclusi i gesti sul touchpad e lo scorrimento con la rotellina del mouse. Consulta Tastiera, mouse e trackpad.

Come disattivare o annullare l'override

Dichiara FEATURE_PC in un elemento <uses-feature> nel manifest dell'applicazione.

<uses-feature android:name="android.hardware.type.pc"
              android:required="false" />

Nota:imposta android:required="false" in modo che la funzionalità per PC sia facoltativa e Google Play non escluda l'applicazione sui dispositivi non PC.

Flag delle proprietà per regolare l'override

Nessuno.

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MOUSE_TO_TOUCH <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MOUSE_TO_TOUCH <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

FORCE_RESIZE_APP

Forza i pacchetti a cui viene applicato l'override in modo che siano ridimensionabili e possano entrare in modalità multi-finestra. Si applica a tutte le dimensioni dei display.

In che modo le app possono ottenere lo stesso risultato dell'override

Nel manifest dell'app, imposta l'attributo android:resizeableActivity su true.

Come ottimizzare le app

Utilizza layout adattabili per consentire alle app di adattarsi a tutte le dimensioni e proporzioni del display. Consulta Supporta diverse dimensioni di display.

Come disattivare o annullare l'override

Imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES su false.

Flag delle proprietà per regolare l'override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

Comandi adb per testare l'override

Per applicare l'override e rendere l'app ridimensionabile:

adb shell am compat enable FORCE_RESIZE_APP <package>

Per rimuovere l'override:

adb shell am compat disable FORCE_RESIZE_APP <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

FORCE_NON_RESIZE_APP

Forza i pacchetti a cui viene applicato l'override in modo che non siano ridimensionabili e entrino in modalità di compatibilità delle dimensioni in caso di modifiche alla configurazione. Si applica a tutte le dimensioni di visualizzazione.

In che modo le app possono ottenere lo stesso risultato dell'override

Imposta l'attributo android:resizeableActivity e il flag dei metadati android.supports_size_changes su false nel manifest dell'app e dichiara una limitazione di orientamento o proporzioni.

Come ottimizzare le app

Tutte le app che si comportano correttamente se ridimensionate devono avere android:resizeableActivity o android.supports_size_changes impostato su true. Le altre app devono essere migliorate per funzionare correttamente quando vengono ridimensionate. Consulta android:resizeableActivity.

Come disattivare o annullare l'override

Imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES su false.

Flag delle proprietà per regolare l'override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

Comandi adb per testare l'override

Per applicare l'override e rendere l'app non ridimensionabile:

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

Per rimuovere l'override:

adb shell am compat disable FORCE_NON_RESIZE_APP <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_MIN_ASPECT_RATIO

Il gatekeeper per tutti gli override che forzano un determinato formato minimo.

In che modo le app possono ottenere lo stesso risultato dell'override

Imposta android:minAspectRatio a livello di attività o di app.

Come ottimizzare le app

Non impostare limitazioni relative alle proporzioni nella tua app. Assicurati che l'app supporti dimensioni di visualizzazione diverse. Utilizza le classi di dimensioni delle finestre per supportare layout diversi in base allo spazio disponibile per l'app sullo schermo. Consulta l'API Compose WindowSizeClass e l'API View WindowSizeClass.

Come disattivare o annullare l'override

Specifica una limitazione delle proporzioni o imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE su false.

Flag delle proprietà per regolare l'override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE"
  android:value="false"/>

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Limita le impostazioni dell'app che forzano un determinato formato minimo per le attività con orientamento solo verticale. Questa opzione è abilitata per impostazione predefinita e ha effetto solo se è abilitata anche l'opzione OVERRIDE_MIN_ASPECT_RATIO.

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_MIN_ASPECT_RATIO_SMALL

Imposta le proporzioni minime dell'attività su un valore ridotto (4:3).

In che modo le app possono ottenere lo stesso risultato dell'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come ottimizzare le app

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come disattivare o annullare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà per regolare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

Imposta le proporzioni minime dell'attività su un valore medio (3:2).

In che modo le app possono ottenere lo stesso risultato dell'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come ottimizzare le app

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come disattivare o annullare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà per regolare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_MIN_ASPECT_RATIO_LARGE

Imposta le proporzioni minime dell'attività su un valore elevato (16:9).

In che modo le app possono ottenere lo stesso risultato dell'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come ottimizzare le app

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come disattivare o annullare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà per regolare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN

Consente l'utilizzo delle proporzioni dello schermo diviso. Consente a un'app di utilizzare tutto lo spazio disponibile in modalità schermo diviso, evitando il letterboxing.

In che modo le app possono ottenere lo stesso risultato dell'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come ottimizzare le app

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come disattivare o annullare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà per regolare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN

Disattiva l'override delle proporzioni minime in modalità a schermo intero verticale per utilizzare tutto lo spazio disponibile sullo schermo.

In che modo le app possono ottenere lo stesso risultato dell'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come ottimizzare le app

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Come disattivare o annullare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà per regolare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_ANY_ORIENTATION

Consente ai seguenti override di eseguire l'override di qualsiasi orientamento:

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

In che modo le app possono ottenere lo stesso risultato dell'override

Imposta l'attributo manifest activity:screenOrientation o utilizza l'API Activity#setRequestedOrientation().

Come ottimizzare le app

L'app deve supportare tutti gli orientamenti. Una modifica dell'orientamento è una modifica della configurazione, che può essere gestita in due modi: consentendo al sistema di distruggere e ricreare l'app o gestendo autonomamente le modifiche alla configurazione. Se gestisci autonomamente le modifiche alla configurazione, lo stato dell'app può essere conservato utilizzando ViewModel. In casi molto limitati, puoi decidere di bloccare l'orientamento solo sui display di piccole dimensioni, anche se questa operazione potrebbe non essere scalabile come consentire all'utente di ruotare l'app in base alle esigenze. Su Android 12L e versioni successive, l'orientamento fisso può essere sostituito dalla configurazione del dispositivo. Per maggiori informazioni sulla gestione delle modifiche alla configurazione e sul supporto di tutti gli orientamenti, consulta Gestisci le modifiche alla configurazione, Panoramica di ViewModel e Orientamento dell'app limitato sugli smartphone, ma non sui dispositivi con schermi grandi.

Come disattivare o annullare l'override

Imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE su false.

Flag delle proprietà per regolare l'override

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"
  android:value="true|false"/>

Comandi adb per testare l'override

Per applicare l'override:

adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>

Per rimuovere l'override:

adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>

Nota:i comandi applicano o rimuovono l'override solo temporaneamente.

OVERRIDE_ANY_ORIENTATION_TO_USER

Consente all'app di riempire lo spazio di visualizzazione disponibile. Esegue l'override di eventuali limitazioni di orientamento, ridimensionamento e proporzioni specificate nel manifest dell'app. Ignora anche tutte le chiamate a Activity#setRequestedOrientation() o Activity#getRequestedOrientation().

In che modo le app possono ottenere lo stesso risultato dell'override

Non impostare l'attributo manifest android:screenOrientation o impostalo su "user".
Imposta l'attributo manifest android:resizeableActivity su true.

Nota: le impostazioni per android:minAspectRatio e android:maxAspectRatio vengono ignorate se resizeableActivity è impostato su true.
Sui piccoli schermi, per supportare il ridimensionamento delle app e disattivare la modalità multi-finestra con android:resizeableActivity=false, imposta il flag dei metadati android.supports_size_changes su true. Non impostare minAspectRatio e maxAspectRatio.

Nota: su Android 12 (livello API 31), tutte le app vengono eseguite in modalità multi-finestra su schermi di grandi dimensioni (classe di dimensioni della finestra media o espansa), indipendentemente dalla configurazione dell'app. Consulta Supporta la modalità multi-finestra.

Come ottimizzare le app

Attiva l'app per supportare tutti gli orientamenti; non impostare una specifica screenOrientation nel manifest dell'app. Supporta la ridimensionabilità delle app, la modalità multi-finestra e tutte le proporzioni del display impostando l'attributo android:resizeableActivity nel manifest dell'app su true. Consulta Supporta diverse dimensioni di display.

Modalità di compatibilità del dispositivo Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Android 16

Disattiva

Dichiara la proprietà manifest

Dispositivi di riferimento

Problemi di compatibilità comuni

Letterboxing

Problema

App limitata all'orientamento verticale non utilizzabile su un dispositivo con orientamento orizzontale.

Ottimizzazione

L'app supporta tutti gli orientamenti del dispositivo.

Soluzione alternativa per la compatibilità

Modalità di compatibilità delle dimensioni

Problema

L'app non ridimensionabile si arresta in modo anomalo in modalità multi-finestra.

Ottimizzazione

L'app funziona con tutte le dimensioni della finestra.

Soluzione alternativa per la compatibilità

App solo in modalità verticale con formato letterbox in orientamento orizzontale, ridimensionata dal controllo di riavvio.

Modalità di compatibilità del display

Loop tremolanti

Problema

L'app solo orizzontale sul display verticale effettua chiamate ripetute a Activity#setRequestedOrientation().

Ottimizzazione

L'app gestisce la modifica della configurazione, non ha limitazioni di orientamento, quindi non entra in un loop di sfarfallio.

Soluzione alternativa per la compatibilità

Anteprima fotocamera

Problema

Anteprima della fotocamera disallineata e distorta su un dispositivo pieghevole con schermo grande.

Ottimizzazione

Anteprima della fotocamera allineata e ridimensionata correttamente in tutti gli orientamenti del dispositivo.

Soluzione alternativa per la compatibilità

Tablet: forza la rotazione dell'app con orientamento verticale limitato.

Pieghevole: rotazione forzata dell'app con limitazione alla modalità Ritratto. L'app è anche in formato letterbox.

API comunemente utilizzate in modo improprio

Problema

L'API deprecata calcola in modo errato i limiti dell'app. I contenuti dell'app escono dallo schermo.

Ottimizzazione

L'API calcola correttamente le metriche della finestra dell'app.

Soluzione alternativa per la compatibilità

Attività trasparenti

Problema

Finestra di dialogo posizionata in modo errato perché l'attività è stata avviata da un trampolino.

Ottimizzazione

Angoli arrotondati

Finestra di dialogo con angoli arrotondati posizionata correttamente sopra l'attività di avvio visibile.

Soluzione alternativa per la compatibilità

Giochi Unity

Problema

Il gioco perde lo stato attivo in modalità multi-finestra e viene visualizzato come una finestra nera.

Ottimizzazione

Il gioco esegue il rendering dei contenuti correttamente in modalità multi-finestra anche quando non è attivo.

Soluzione alternativa per la compatibilità

Finestre delle app

Le app con orientamento bloccato possono comunque essere ridimensionate liberamente.

L'UI delle attività dichiarate come non ridimensionabili viene scalata.

Anteprima della fotocamera in modalità finestre delle app

Problema

Ottimizzazione

Soluzione alternativa per la compatibilità

Ridimensionamento

Ridimensionamento di una finestra con il mirino della fotocamera

Testa la tua app per individuare eventuali problemi di compatibilità

È in formato letterbox

Kotlin

Java

Kotlin

Java

Override per app

Override per app dell'utente

Override per app del dispositivo

OVERRIDE_MOUSE_TO_TOUCH

In che modo le app possono ottenere lo stesso risultato dell'override

Come ottimizzare le app

Come disattivare o annullare l'override

Flag delle proprietà per regolare l'override

Comandi adb per testare l'override

FORCE_RESIZE_APP

In che modo le app possono ottenere lo stesso risultato dell'override

Come ottimizzare le app

Modalità di compatibilità del dispositivo

L'app solo orizzontale sul display verticale effettua chiamate ripetute a `Activity#setRequestedOrientation()`.