Questa pagina è stata tradotta dall'API Cloud Translation.

Modalità di compatibilità del dispositivo

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

Le sostituzione per app consentono ai produttori di dispositivi di modificare il comportamento delle app per migliorare l'esperienza utente o impedire il malfunzionamento delle app su dispositivi specifici.

Dispositivi di riferimento

I seguenti dispositivi potrebbero richiedere sostituzioni per app a causa di configurazioni insolite o non 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 verticale, i layout delle app e l'anteprima della fotocamera potrebbero non corrispondere al display del dispositivo.
Dispositivi pieghevoli orizzontali: alcuni dispositivi pieghevoli, come Pixel Fold, sono in orientamento verticale quando sono chiusi, ma in orizzontale quando sono aperti. Se le app presuppongono che l'orientamento sia verticale, è probabile che si verifichino loop con sfarfallio o problemi di layout.
Smartphone pieghevoli con apertura a conchiglia:quando sono aperti, gli smartphone con apertura a conchiglia sono in genere in orientamento verticale. Tuttavia, quando sono chiusi, gli smartphone di solito hanno un piccolo display in orientamento orizzontale. Le app devono identificare e supportare i diversi orientamenti dei display.

Problemi di compatibilità comuni

Le app riscontrano problemi di compatibilità più spesso a causa di limitazioni relative all'orientamento, alla modifica delle dimensioni e alle proporzioni, alla gestione errata dell'orientamento dell'anteprima della fotocamera e all'uso improprio delle API.

Letterboxing

Con il letterbox, l'app viene posizionata al centro dello schermo o, su schermi di grandi dimensioni, su un lato o sull'altro per un accesso pratico. Le aree opache (barre di colore uniforme o sfondo sfocato) riempiono l'area di visualizzazione inutilizzata lungo i lati o nella parte superiore e inferiore dell'app.

Il letterbox si verifica spesso sui dispositivi con schermi di grandi dimensioni perché le dimensioni e il formato dello schermo del dispositivo sono in genere diversi da quelli degli smartphone standard, per i quali è progettata la maggior parte delle app.

Figura 1. L'app limitata all'orientamento verticale è letterboxed sui tablet e sui dispositivi pieghevoli in orizzontale.

Problema

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

Le impostazioni di configurazione che controllano l'orientamento e la modifica delle dimensioni dell'app includono quanto segue:

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 in modo che si adattino 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 piccoli (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 formato orizzontale massimo supportato dall'app. Solo le app con resizeableActivity impostato su false possono impostare maxAspectRatio.
minAspectRatio: specifica il formato orizzontale minimo supportato dall'app. Solo le app con resizeableActivity impostato su false possono impostare minAspectRatio.

L'app limitata all'orientamento verticale non è utilizzabile su un dispositivo in orizzontale.

Ottimizzazione

L'app deve supportare tutti gli orientamenti e le dimensioni dei display dei dispositivi e della modalità multifinestra. 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 la inserisce in una finestra con bordi neri 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 con letterbox. I produttori di dispositivi implementano i miglioramenti dell'interfaccia utente. Non è necessario alcun sviluppo aggiuntivo per la tua app per 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 sovrappongono l'app, sono semitrasparenti, quindi le icone sulle barre sono sempre visibili sullo sfondo letterbox.
Formato configurabile:le proporzioni dell'app possono essere regolate per migliorarne l'aspetto.

Figura 2. App con letterbox e miglioramenti all'interfaccia utente.

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

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

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

Figura 3. App con riquadro nero e finestra di dialogo informativa per l'utente.

Modalità di compatibilità delle dimensioni

La modalità di compatibilità delle dimensioni è letterbox 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 contenitore del display incompatibile con le sue dimensioni, il sistema potrebbe ridimensionare l'app in modo da 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 limitazioni di orientamento o proporzioni e che sono configurate (o determinate dal sistema) come non ridimensionabili.

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

È ridimensionabile con resizeableActivity="true"
Supporta la modalità picture in picture (PIP)
È incorporata
È stata applicata 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, è considerata non ridimensionabile e potrebbe essere inserita in 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 dei display. Rendi la tua app ridimensionabile impostando l'attributo android:resizeableActivity dell'elemento <activity> o <application> su true nel file manifest dell'app. Progetta layout adattabili/responsive per la tua app. Per ulteriori informazioni, consulta Supportare dimensioni diverse del display e Supportare la modalità multi-finestra.

L'app funziona in tutte le dimensioni della finestra.

Soluzione alternativa per la compatibilità

Android inserisce un'app in modalità di compatibilità delle dimensioni quando il sistema determina che la visualizzazione dell'app con letterbox può essere migliorata ridimensionando l'app in modo da riempire la finestra di visualizzazione in almeno una dimensione. Il sistema mostra un controllo di riavvio che ricrea il processo dell'app, ricrea l'attività e ridisegna il display. Consulta anche la Panoramica di processi e thread.

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

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 fa 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 da ignorare le limitazioni dell'orientamento specificate dalle app e applicare le modalità di compatibilità. Ad esempio, un dispositivo pieghevole potrebbe ignorare un'impostazione android:screenOrientation="portrait" di un'attività quando l'attività viene visualizzata sullo schermo interno del dispositivo in formato tablet orizzontale.

Se le limitazioni dell'orientamento di un'app vengono ignorate, l'app può impostare il proprio orientamento in modo programmatico chiamando Activity#setRequestedOrientation(). La chiamata attiva un riavvio dell'app se l'app non gestisce le modifiche alla configurazione (vedi Gestire le modifiche alla configurazione). Dopo il riavvio, le limitazioni dell'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 autonomo.

Un altro caso in cui potresti riscontrare questo problema si verifica quando l'orientamento naturale (l'orientamento usuale come stabilito da Android) dello schermo di un dispositivo è orizzontale (ovvero, l'istruzione Display#getRotation() restituisce Surface.ROTATION_0 mentre il dispositivo ha un formato orizzontale). In passato, le app presumevano che Display.getRotation() = Surface.ROTATION_0 indicasse 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 in orientamento orizzontale su un display interno pieghevole potrebbe controllare la rotazione dello schermo, ricevere un valore ROTATION_0, assumere 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 in orizzontale in modalità di visualizzazione verticale effettua chiamate ripetute a `Activity#setRequestedOrientation()`.

Ottimizzazione

Le app non devono:

Imposta un'opzione di orientamento predefinita 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
Supponiamo che l'orientamento naturale del dispositivo (ROTATION_0) sia verticale
Imposta l'orientamento in base a indicatori non correlati alle dimensioni attuali della finestra, come Display#getRotation(), la presenza di un FoldingFeature o di API ritirate.

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 riavviata da una chiamata precedente al metodo o è stato attivato il trattamento di rotazione forzata della compatibilità con la videocamera (vedi Anteprima della videocamera 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.

Anteprima fotocamera

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

Problema

Il Compatibility Definition Document (CDD) di Android afferma che un sensore di immagine della fotocamera "DEVE essere orientato in modo che la dimensione lunga della fotocamera si allinei alla dimensione lunga dello schermo".

Spesso le app presuppongono che l'orientamento del dispositivo e quello del sensore della fotocamera siano in verticale, un'ipotesi ragionevole per i telefoni cellulari standard. Tuttavia, l'orientamento naturale dei tablet e dei laptop e dei relativi sensori della fotocamera può essere orizzontale. Inoltre, i nuovi fattori di forma come i dispositivi 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 del dispositivo all'altro (per i dispositivi pieghevoli) può causare un'anteprima della fotocamera non allineata o distorta.

Anteprima della fotocamera non allineata e distorta su dispositivo pieghevole con schermo grande.

Ottimizzazione

Le app della fotocamera devono identificare e gestire correttamente l'orientamento del dispositivo e l'orientamento del sensore della fotocamera per presentare un'anteprima della fotocamera allineata e scalata correttamente. Le app devono calcolare la rotazione del dispositivo, la rotazione del sensore e il formato 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.

L'anteprima della fotocamera sia allineata e scalata 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 in base all'orientamento naturale del dispositivo. Android allinea la finestra verticale delle app con limitazioni in verticale all'orientamento naturale del dispositivo, che è ciò che la maggior parte delle app si aspetta. 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 quanto segue:

Forza la rotazione delle anteprime della fotocamera per le app con limitazioni in verticale: le app con limitazioni all'orientamento verticale prevedono che l'orientamento naturale del dispositivo e l'orientamento del sensore della fotocamera siano in verticale. 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 in modalità Ritratto è collegata alla fotocamera, Android forza la rotazione dell'app per allineare la finestra dell'app in modalità Ritratto all'orientamento naturale del dispositivo.

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

Tablet: forza la rotazione dell'app con limitazioni in verticale.

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

Pieghevole: forza la rotazione dell'app con limitazioni in modalità Ritratto. L'app è anche in letterbox.

Nota: la rotazione forzata non si verifica se l'app è adattabile e gestisce gli orientamenti verticale e orizzontale.
Ritaglio della fotocamera anteriore interna: il sensore della fotocamera anteriore interna su alcuni dispositivi 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.
Aggiorna forzosamente le anteprime della videocamera: il sistema passa attraverso i metodi di attività onStop() e onStart() (per impostazione predefinita) o onPause() eonResume() (applicati dall'OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE sovrascrivi per app) dopo la rotazione forzata per assicurarsi che l'anteprima della videocamera sia visualizzata correttamente.
Ridimensionamento delle proporzioni:il sistema modifica dinamicamente le proporzioni dell'anteprima della fotocamera con rotazione forzata in modo da ottenere proporzioni minime più elevate, il che garantisce che l'anteprima della fotocamera sia ridimensionata correttamente.

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

API di uso improprio comune

Poiché Android ha aggiunto il supporto di funzionalità come la modalità multi-finestra e dispositivi come i pieghevoli, le API precedenti sono state ritirate e sostituite da API aggiornate che funzionano per tutti i formati del display e i fattori di forma 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 confini dell'app anziché i confini dell'area di visualizzazione del dispositivo. In alternativa, gli sviluppatori utilizzano erroneamente API di visualizzazione a scopo speciale per ottenere metriche generali sulle visualizzazioni. Il risultato è un calcolo errato durante il riposizionamento degli elementi dell'interfaccia utente dopo gli eventi di ridimensionamento della finestra dell'app, causando problemi di layout.

API display deprecate e di uso comune improprio:

Per ulteriori informazioni, consulta la sezione Supportare la modalità multi-finestra.

API di visualizzazione usate in modo improprio:

L'API obsoleta calcola erroneamente i limiti dell'app. I contenuti dell'app non sono visibili sullo schermo.

Ottimizzazione

Non fare mai affidamento sulle dimensioni fisiche del display per il posizionamento degli elementi dell'interfaccia utente. Esegui la migrazione della tua app alle API basate su WindowMetrics, tra cui 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 sostituzioni regolano le API Display ritirate e le API View usate 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à con le 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 correlati 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 di configurazione come la rotazione, la chiusura e l'apertura 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à della task. Tuttavia, un'attività opaca che avvia una finestra di dialogo di autorizzazione può essere un'attività trampolino (un'attività che avvia un'altra attività e poi scompare); pertanto, il sistema non può determinare i limiti dell'attività trampolino che ha avviato l'attività della finestra di dialogo di autorizzazione trasparente.

Dialogo posizionato in modo errato perché l'attività è stata avviata da un trampolino.

Ottimizzazione

Le attività trasparenti ereditano i vincoli dall'attività opaca più in alto al di sotto di esse nella pila di attività di un'attività. L'attività opaca deve essere disponibile per l'intero ciclo di vita dell'attività trasparente, dalla creazione alla distruzione. Per questo motivo, non avviare richieste di autorizzazione dalle attività di trampoline.

Se un'attività trampolino avvia una richiesta di autorizzazione, l'utente potrebbe non essere in grado di visualizzare la finestra di dialogo di autorizzazione perché l'attività trampolino sarà stata distrutta 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 alle autorizzazioni.

Angoli arrotondati

Un'attività può essere trasparente a causa di uno stile che specifica la trasparenza dell'background 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 il produttore del dispositivo lo ha configurato. Tuttavia, se un'attività trasparente (ad esempio una dialoga di autorizzazione) non riempie lo spazio disponibile, sta a te decidere se applicare o meno i bordi arrotondati.

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

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

Soluzione alternativa per la compatibilità

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

Il sistema assicura che un'attività trasparente erediti tutti i vincoli della prima attività opaca sotto l'attività trasparente nello stack di 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à multifinestra. Tuttavia, molti giochi Unity perdono il focus e smettono di disegnare i contenuti quando l'app viene posizionata in modalità multifinestra.

Problema

In Unity 2019.4 è stata aggiunta un'opzione Resizable Window per supportare la modalità multi-finestra su Android. Tuttavia, l'implementazione iniziale non ha reagito correttamente al ciclo di vita dell'attività in modo multi-finestra, causando la sospensione della riproduzione da parte di UnityPlayer quando l'app perde il focus. Il player ha visualizzato una schermata nera o l'ultimo frame bloccato del gioco. Il gameplay è ripreso solo quando l'utente ha toccato lo schermo. Molte app che utilizzano il motore Unity presentano 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 a Unity 2019.4.40 o versioni successive ed esporta di nuovo il gioco. Mantieni selezionata l'opzione Resizable Window nelle impostazioni del player Android, 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_ENABLE_COMPAT_FAKE_FOCUS override per app per fornire un evento di messa a fuoco falso a un'app in modo multi-finestra. L'override consente all'attività di ridisegnare i contenuti e di non essere oscurata.

Verificare la presenza di problemi di compatibilità dell'app

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

Streaming di dispositivi: per testare la tua app su dispositivi di produzione (inclusi dispositivi di riferimento) ospitati nei data center di Google, consulta Streaming di dispositivi Android, basato su Firebase
Emulatori in Android Studio Hedgehog: per informazioni sulla creazione di emulatori per dispositivi di riferimento, consulta Creare e gestire dispositivi virtuali.
Emulatore Android Studio ridimensionabile:per informazioni su come accedere ai dispositivi virtuali, consulta Eseguire app nell'emulatore Android

È 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 Activity.isLetterboxed() : 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()
    }
}

Java

public boolean isLetterboxed(Activity 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();
}

Esegui un test per verificare il comportamento e assicurarti che l'attività target non sia inscritta in una casella:

Kotlin

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

@Test
fun activity_launched_notLetterBoxed() {
    activityRule.scenario.onActivity {
        assertThat(it.isLetterboxed()).isFalse()
    }
}

Java

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

public void activity_launched_notLetterBoxed() {
    try (ActivityScenario<MainActivity> scenario = ActivityScenario.launch(MainActivity.class)) {
        scenario.onActivity(activity -> {
            assertThat(isLetterboxed(activity)).isFalse();
        });
    }
}

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

Sostituzioni per app

Android fornisce sostituzioni 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 base alle dimensioni del display anche se resizeableActivity="false" è specificato nel manifest dell'app.

I produttori di dispositivi applicano sostituzioni ad app selezionate o a tutte le app su dispositivi con schermi di grandi dimensioni specifici. Su Android 14 (livello API 34) e versioni successive, gli utenti possono applicare sostituzioni alle app tramite le impostazioni del dispositivo.

Override per app per utente

Su Android 14 e versioni successive, un menu delle impostazioni consente agli utenti di modificare il formato 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 impostano il formato dell'app su 3:4, 1:1, a schermo intero o su un altro valore configurato dal produttore del dispositivo. Gli utenti possono anche reimpostare il formato in quello predefinito dell'app, specificato nel file manifest dell'app.

Le app possono disattivare la sostituzione della compatibilità impostando i seguenti tag PackageManager.Property:

PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE

Per disattivare l'override della compatibilità con il formato 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>
```
L'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 dell'utente, aggiungi la proprietà al file 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 formato 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 delle proporzioni nella tua app. Utilizza le classi di dimensioni della finestra per supportare diversi layout in base alla quantità di spazio di visualizzazione disponibile.

Sostituzioni per app del produttore del dispositivo

I produttori di dispositivi applicano le sostituzioni su base app su dispositivi selezionati. I dispositivi di riferimento potrebbero applicare alcune delle sostituzioni a una serie di app per impostazione predefinita.

Le app possono disattivare la maggior parte delle sostituzioni (vedi la tabella Sostituzioni per app di seguito).

Puoi testare la tua app con le sostituzioni attivate o disattivate utilizzando il framework di compatibilità (vedi Strumenti del framework di compatibilità). Se sono attivate, le sostituzioni vengono applicate all'intera app.

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

Attiva o disattiva le sostituzioni come segue:

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

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

adb shell dumpsys platform_compat | grep <package name>

La tabella seguente elenca le sostituzioni disponibili, oltre a indicazioni su come ottimizzare l'app in modo che non debba fare affidamento su sostituzioni. Puoi aggiungere flag di proprietà al file manifest dell'app per disattivare alcune sostituzioni.

Sostituzioni per app
Digitazione	Nome	ID	Descrizione
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à con le dimensioni in caso di modifiche alla configurazione.
Proporzioni	OVERRIDE_MIN_ASPECT_RATIO	174042980	Sostituzione del gatekeeper che deve essere attivata per applicare qualsiasi altra sostituzione del formato.
	OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY	203647190	Se è attivata (impostazione predefinita), i limiti sostituiscono l'ambito con le attività solo in formato verticale.
	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 in modo che il video occupi il 50% delle dimensioni del display (o le proporzioni dello schermo diviso).
	OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN	218959984	Disattiva l'override delle proporzioni minime in modo che le app siano a schermo intero quando il dispositivo è in orientamento verticale.
Orientamento	OVERRIDE_ANY_ORIENTATION	265464455	Consente di ignorare qualsiasi orientamento.
	OVERRIDE_ANY_ORIENTATION_TO_USER	310816437	Sostituisce le limitazioni relative all'orientamento, alla modifica delle dimensioni e alle proporzioni.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT	265452344	Sostituisce l'orientamento in verticale quando un'attività ha un orientamento non definito.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	Sostituisce l'orientamento con `nosensor` (utilizza l'orientamento naturale del dispositivo) quando un'attività ha un orientamento non definito.
	OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE	266124927	Ruota le app solo in orizzontale di 180 gradi.
	OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA	265456536	Limita l'ambito dell'override dell'orientamento al momento in cui l'app è connessa alla videocamera.
	OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION	255940284	Imposta la visualizzazione sull'orientamento naturale orizzontale fisso quando un'attività è a schermo intero (anche con letterbox).
	OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION	254631730	Ignora le richieste di orientamento dall'app per evitare cicli 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 lo considera un ciclo infinito di rotazione e applica l'override.
	OVERRIDE_RESPECT_REQUESTED_ORIENTATION	236283604	Impedisce il letterboxing disattivando l'impostazione della richiesta di ignorare l'orientamento del produttore del dispositivo.
API sandbox	NEVER_SANDBOX_DISPLAY_APIS	184838306	Impedisce di modificare il 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 presume 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 presume che le API `View` restituiscano i limiti dell'app, il che causa problemi di UI.
Fotocamera compatta	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 è aperta l'anteprima della fotocamera.
	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	Passa l'aggiornamento forzato a un aggiornamento graduale quando l'anteprima di una videocamera viene ruotata forzatamente, il che contribuisce a preservare lo stato durante la rotazione forzata. Per impostazione predefinita, Android applica un aggiornamento forzato quando l'anteprima della fotocamera viene ruotata forzatamente. L'aggiornamento forzato può causare problemi con le app che perdono lo stato o diventano nere, a seconda di come le app hanno memorizzato nella cache il loro stato precedente.
	OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT	250678880	Ritaglia il buffer delle 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 dispositivi pieghevoli (vedi Dispositivi di riferimento), il sistema ritaglia l'anteprima della fotocamera di tutte le app di fotocamera quando viene utilizzata la fotocamera anteriore interna.
Vari	OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS	263259275	Impedisce che l'app venga oscurata quando perde lo stato attivo in modalità schermo diviso. L'app attende di essere attivata prima di disegnare i contenuti, il che può causare il blocco o l'oscuramento dell'app. L'override consente ad Android di inviare all'app un falso evento di attivazione, che indica all'app di iniziare di nuovo a disegnare i contenuti.

FORCE_RESIZE_APP

Forza i pacchetti a cui viene applicata la sostituzione a essere ridimensionabili. Non cambia la possibilità di mettere l'app in modalità multifinestra, ma consente di ridimensionarla senza attivare la modalità di compatibilità delle dimensioni quando lo schermo cambia dimensioni.

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

Nel file manifest dell'app, imposta l'attributo android:resizeableActivity su true oppure, per supportare il ridimensionamento disattivando la modalità multi-finestra con android:resizeableActivity=false, imposta il flag dei metadati android.supports_size_changes su true.

Come ottimizzare le app

Utilizza i layout adattabili per consentire alle app di adattarsi a tutte le dimensioni e proporzioni dello schermo. Consulta Supportare dimensioni di visualizzazione diverse.

Come disattivare o disattivare l'override

Imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES su false.

Flag delle proprietà da modificare per 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 la sostituzione:

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 a non essere ridimensionabili e a entrare in modalità di compatibilità delle dimensioni in caso di modifiche alla configurazione.

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

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

Come ottimizzare le app

Per tutte le app che si comportano bene se ridimensionate, deve essere impostato android:resizeableActivity o android.supports_size_changes su true. Altre app devono essere migliorate per funzionare correttamente quando vengono ridimensionate. Vedi android:resizeableActivity.

Come disattivare o disattivare l'override

Imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES su false.

Flag delle proprietà da modificare per 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 impedire la ridimensionabilità dell'app:

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

Per rimuovere la sostituzione:

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 tutte le sostituzioni 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 app.

Come ottimizzare le app

Non impostare limitazioni per il formato dell'aspetto nell'app. Assicurati che l'app supporti diversi formati di display. Utilizza le classi di dimensioni della finestra per supportare layout diversi in base allo spazio a disposizione dell'app sullo schermo. Consulta l'API Compose WindowSizeClass e l'API ViewWindowSizeClass.

Come disattivare o disattivare l'override

Specifica una limitazione del formato o imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE su false.

Flag delle proprietà da modificare per 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 la sostituzione:

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. È attiva per impostazione predefinita e viene applicata solo se è attivata anche 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 la sostituzione:

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_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 disattivare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà da modificare per 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 la sostituzione:

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 disattivare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà da regolare per 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 la sostituzione:

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 di utilizzare le 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 disattivare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà da modificare per 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 la sostituzione:

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 a schermo intero in verticale per utilizzare tutto lo spazio sullo schermo disponibile.

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 disattivare l'override

Vedi OVERRIDE_MIN_ASPECT_RATIO.

Flag delle proprietà da modificare per 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 la sostituzione:

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 di ignorare qualsiasi orientamento tramite le seguenti sostituzioni:

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. La modifica dell'orientamento è una modifica della configurazione che può essere gestita in due modi: lasciando che il sistema distrugga e ricrei l'app o gestendo autonomamente le modifiche della configurazione. Se gestisci personalmente le modifiche alla configurazione, lo stato dell'app può essere conservato utilizzando ViewModel. In casi molto limitati, puoi decidere di bloccare l'orientamento solo su display di piccole dimensioni, anche se questa operazione potrebbe non essere scalabile quanto lasciare che l'utente ruoti l'app in base alle esigenze. Su Android 12L e versioni successive, l'orientamento fisso può essere ignorato dalla configurazione del dispositivo. Per ulteriori informazioni su come gestire le modifiche alla configurazione e supportare tutti gli orientamenti, consulta Gestire le modifiche alla configurazione, Panoramica di ViewModel e Orientamento app limitato su smartphone, ma non su dispositivi con schermi di grandi dimensioni.

Come disattivare o disattivare l'override

Imposta il flag della proprietà PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE su false.

Flag delle proprietà da modificare per 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 la sostituzione:

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. Sostituisce eventuali limitazioni relative a orientamento, ridimensionamento e proporzioni specificate nel file manifest dell'app. Inoltre, ignora le chiamate a Activity#setRequestedOrientation().

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.
Su schermi di piccole dimensioni, per supportare il ridimensionamento delle app disattivando 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à multifinestra su schermi di grandi dimensioni (classe di dimensioni della finestra media o espansa) indipendentemente dalla configurazione dell'app. Consulta Supportare la modalità multi-finestra.

Come ottimizzare le app

Consenti all'app di supportare tutti gli orientamenti; non impostare una specifica screenOrientation nel manifest dell'app. Supporta la modifica delle dimensioni dell'app, la modalità multifinestra e tutti i rapporti di aspetto del display impostando l'attributo android:resizeableActivity nel file manifest dell'app su true. Consulta Supportare dimensioni di visualizzazione diverse.

Modalità di compatibilità del dispositivo

Dispositivi di riferimento

Problemi di compatibilità comuni

Letterboxing

Problema

L'app limitata all'orientamento verticale non è utilizzabile su un dispositivo in 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 in tutte le dimensioni della finestra.

Soluzione alternativa per la compatibilità

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

Loop tremolanti

Problema

L'app solo in orizzontale in modalità di visualizzazione 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 non allineata e distorta su dispositivo pieghevole con schermo grande.

Ottimizzazione

L'anteprima della fotocamera sia allineata e scalata correttamente in tutti gli orientamenti del dispositivo.

Soluzione alternativa per la compatibilità

Tablet: forza la rotazione dell'app con limitazioni in verticale.

Pieghevole: forza la rotazione dell'app con limitazioni in modalità Ritratto. L'app è anche in letterbox.

API di uso improprio comune

Problema

L'API obsoleta calcola erroneamente i limiti dell'app. I contenuti dell'app non sono visibili sullo schermo.

Ottimizzazione

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

Soluzione alternativa per la compatibilità

Attività trasparenti

Problema

Dialogo posizionato 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 lancio 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à

Verificare la presenza di problemi di compatibilità dell'app

È letterbox

Kotlin

Java

Kotlin

Java

Sostituzioni per app

Override per app per utente

Sostituzioni per app del produttore del dispositivo

FORCE_RESIZE_APP

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

Come ottimizzare le app

Come disattivare o disattivare l'override

Flag delle proprietà da modificare per l'override

Comandi adb per testare l'override

FORCE_NON_RESIZE_APP

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

Come ottimizzare le app

Come disattivare o disattivare l'override

Flag delle proprietà da modificare per l'override

Comandi adb per testare l'override

OVERRIDE_MIN_ASPECT_RATIO

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

Come ottimizzare le app

Come disattivare o disattivare l'override

Flag delle proprietà da modificare per l'override

Comandi adb per testare l'override

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

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

Come ottimizzare le app

Come disattivare o disattivare l'override

L'app solo in orizzontale in modalità di visualizzazione verticale effettua chiamate ripetute a `Activity#setRequestedOrientation()`.