Guida alla configurazione della compatibilità delle app per schermi di grandi dimensioni

La pagina fornisce una guida e un indice completi per le configurazioni di compatibilità delle app per schermi di grandi dimensioni di Android.

Display

Questa sezione elenca tutte le impostazioni di configurazione che influiscono sulla configurazione a livello di display.

Nome Posizione Tipo Predefinito
ignoreOrientationRequest display_settings.xml config false
true per schermi grandi (>= 600 dp)
Descrizione
Consente la rotazione senza costi delle attività a orientamento fisso sullo schermo specificato.
Esempio: 
          <display-settings>
              <config identifier="0" />
              <display
                  name="<display's uniqueId>"
                  ignoreOrientationRequest="true"/>
          </display-settings>

Caso d'uso o contesto
Il display ignora l'orientamento richiesto di tutte le app e l'app è letterbox.
Utilizzato su tutti i dispositivi con schermo di grandi dimensioni e su Android Automotive OS. Questa è l'impostazione predefinita per tutti i dispositivi con schermo di grandi dimensioni con smallestScreenWidthDp >= 600dp in Android 16 e versioni successive.
config_letterboxIsDisplayRotationImmersiveAppCompatPolicyEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Attiva il criterio di compatibilità della rotazione per le app immersive che impedisce la rotazione automatica in un orientamento dello schermo non ottimale in modalità a schermo intero. Questo è necessario perché le app immersive, come i giochi, spesso non sono ottimizzate per tutti gli orientamenti e possono avere una UX scadente quando vengono ruotate. Inoltre, alcuni giochi si basano sui sensori per il gameplay, quindi gli utenti possono attivare queste rotazioni accidentalmente quando la rotazione automatica è attiva.
Si applica solo se ignoreOrientationRequest è attivato.

Caso d'uso o contesto
Blocca la rotazione per le app immersive.

Proporzioni

Questa sezione elenca tutte le impostazioni di configurazione che influiscono sulla configurazione della finestra a livello di attività per le proporzioni.

Nome Posizione Tipo Predefinito
config_fixedOrientationLetterboxAspectRatio frameworks/base/core/res/res/values/config.xml Float 0.0
Descrizione
Configura le proporzioni del letterbox per l'orientamento fisso. I valori minori o uguali a 1.0 vengono ignorati.

Caso d'uso o contesto
Configura le proporzioni predefinite del dispositivo che funzionano per la maggior parte delle app letterbox. Di solito più vicino a un formato quadrato.
config_letterboxIsSplitScreenAspectRatioForUnresizableAppsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se utilizzare le proporzioni dello schermo diviso come proporzioni predefinite per le app non ridimensionabili.

Caso d'uso o contesto
La maggior parte delle app non ridimensionabili si aspetta un layout per smartphone candybar verticale.
config_letterboxIsDisplayAspectRatioForFixedOrientationLetterboxEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se utilizzare le proporzioni di visualizzazione come proporzioni predefinite per tutte le app letterbox.

Caso d'uso o contesto
Una configurazione per utilizzare programmaticamente le proporzioni di visualizzazione anziché configurare un valore float.

Fotocamera

Questa sezione elenca tutte le impostazioni di configurazione che influiscono sulle app al callback di onCameraOpened. Queste impostazioni possono influire sulla visualizzazione, sull'attività e sulla configurazione della videocamera.

Nome Posizione Tipo Predefinito
config_isWindowManagerCameraCompatTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Attiva il trattamento di compatibilità della videocamera per i problemi causati da una mancata corrispondenza dell'orientamento tra i buffer della videocamera e una finestra dell'app.
Ciò include la rotazione forzata delle attività a orientamento fisso collegate alla videocamera a schermo intero e la visualizzazione di una descrizione comando in modalità split screen.
Il trattamento di rotazione forzata può essere disattivato tramite l'override per app: OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Caso d'uso o contesto
Corregge le anteprime della videocamera ruotate ruotando forzatamente il display in modo che corrisponda all'orientamento richiesto dall'app.
config_isWindowManagerCameraCompatSplitScreenAspectRatioEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se un'attività utilizza le proporzioni dello schermo diviso quando il trattamento di compatibilità della videocamera è attivato e l'attività è collegata alla videocamera a schermo intero.

Caso d'uso o contesto
Corregge le anteprime della videocamera allungate applicando il letterbox all'attività per ottenere proporzioni simili a quelle di una barretta di cioccolato.
Generalmente utilizzato insieme al trattamento di rotazione forzata abilitato (config_isWindowManagerCameraCompatTreatmentEnabled e camera.enable_landscape_to_portrait) sui dispositivi orizzontali per risolvere i problemi di compatibilità della videocamera allungata simulando le proporzioni a forma di barretta verticale per l'attività.
camera.enable_landscape_to_portrait Proprietà di sistema Bool false
Descrizione
: limita l'accesso al trattamento OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT.
Forza il ritaglio e la rotazione di 90 gradi dell'output della videocamera sulle videocamere con orientamento orizzontale naturale per simulare l'orientamento verticale naturale. L'orientamento del sensore della videocamera segnalato è verticale per tutte le videocamere orizzontali sul dispositivo. Molte app non gestiscono questa situazione e visualizzano immagini allungate.

Caso d'uso o contesto
Consente la rotazione e il ritaglio della HAL della videocamera. Per ulteriori informazioni sul trattamento, vedi Ruotare, ritagliare, scalare.
Aggiungi quanto segue al file mk al momento della build: PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=true
Questo trattamento richiede che il dispositivo supporti SCALER_ROTATE_AND_CROP in HAL. Vedi CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES.
Per indicazioni sull'implementazione specifica dell'HAL per SCALER_ROTATE_AND_CROP, consulta metadata_definitions.xml.

Sfondo e UI

Questa sezione elenca tutte le impostazioni di configurazione applicate alla superficie del livello letterbox per la personalizzazione dell'interfaccia utente o a livello di attività.

Nome Posizione Tipo Predefinito
config_letterboxActivityCornersRadius frameworks/base/core/res/res/values/config.xml Integer 0
Descrizione
Configura il raggio dell'angolo per un'attività presentata in modalità letterbox. I valori inferiori a 0 attivano gli angoli arrotondati con un raggio pari al valore minimo tra i raggi degli angoli inferiori del dispositivo. Un valore predefinito di 0 disattiva la logica degli angoli arrotondati in AppCompatLetterboxPolicy.

Caso d'uso o contesto
Di solito configurato in modo che corrisponda agli angoli arrotondati del dispositivo fisico.
config_letterboxIsEnabledForTranslucentActivities frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se è attivato un comportamento specifico per le attività traslucide letterbox.

Caso d'uso o contesto
Consente di inserire le attività traslucide o le finestre modali in una letterbox e di vincolarle alla configurazione dell'attività letterbox. Le norme si applicano in TransparentPolicy.
config_isCompatFakeFocusEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se l'invio di un focus fittizio di compatibilità per le attività riprese in modalità Split Screen è abilitato.
Ciò è necessario perché alcuni motori di gioco attendono di ottenere lo stato attivo prima di disegnare i contenuti dell'app, che non vengono forniti per impostazione predefinita nelle modalità multi-finestra.

Caso d'uso o contesto
Un flag legacy per applicare il trattamento di compatibilità per i motori di gioco Unity per le app che diventano nere dopo essere entrate in modalità split-screen e vengono disegnate solo dopo che l'utente tocca e mette a fuoco l'app.
config_letterboxBackgroundType frameworks/base/core/res/res/values/config.xml Integer 0
Descrizione
Configura l'aspetto degli angoli dello sfondo letterbox:
  • 0 - Sfondo a tinta unita con il colore specificato in R.color.config_letterboxBackgroundColor.
  • 1 - Colore specificato in R.attr.colorBackground per l'applicazione letterbox.
  • 2 - Colore specificato in R.attr.colorBackgroundFloating per l'applicazione letterbox.
  • 3: sfondo con sfocatura attenuata o scrim scuro. Almeno uno dei seguenti parametri deve essere maggiore di 0: config_letterboxBackgroundWallpaperBlurRadius o config_letterboxBackgroundWallpaperDarkScrimAlpha. In caso contrario o se viene fornito un raggio di sfocatura, ma la sfocatura non è supportata dal dispositivo e questa opzione è selezionata, l'implementazione viene impostata per impostazione predefinita sull'opzione 0. Se il valore specificato non rientra in questo intervallo, viene utilizzata l'opzione 0.


Caso d'uso o contesto
Questa funzionalità non è stata lanciata a causa di problemi di rendimento esistenti. Gli OEM possono creare la propria implementazione di questa funzionalità, ma AOSP non gestirà eventuali bug.
config_letterboxBackgroundColor frameworks/base/core/res/res/values/config.xml Color @color/system_neutral1_1000
Descrizione
Configura il colore dello sfondo letterbox se si verifica una delle seguenti condizioni true:
  • L'opzione 0 è selezionata per R.integer.config_letterboxBackgroundType.
  • L'opzione 1 è selezionata per R.integer.config_letterboxBackgroundType e R.attr.colorBackground non è specificato per l'app.
  • L'opzione 2 è selezionata per R.integer.config_letterboxBackgroundType e R.attr.colorBackgroundFloating non è specificato per l'app.
  • L'opzione 3 è selezionata per R.integer.config_letterboxBackgroundType e viene richiesto l'effetto sfocatura, che non è supportato sul dispositivo, oppure non vengono forniti sia l'alfa della semitrasparenza scura sia il raggio di sfocatura.


Caso d'uso o contesto
Questa funzionalità non è stata lanciata a causa di problemi di rendimento esistenti. Gli OEM possono creare la propria implementazione di questa funzionalità, ma AOSP non gestirà eventuali bug.
config_letterboxBackgroundWallpaperBlurRadius frameworks/base/core/res/res/values/config.xml Dimen 38dp
Descrizione
Configura il raggio di sfocatura per l'opzione 3 in R.integer.config_letterboxBackgroundType. I valori inferiori a 0 vengono ignorati e viene utilizzato 0.

Caso d'uso o contesto
Questa funzionalità non viene lanciata a causa di problemi di rendimento esistenti. Gli OEM possono creare la propria implementazione di questa funzionalità, ma AOSP non gestirà eventuali bug.
config_letterboxBackgroundWallpaperDarkScrimAlpha frameworks/base/core/res/res/values/config.xml Float 0.54
Descrizione
Configura l'alpha di una scrim traslucida nera mostrata sopra lo sfondo letterbox dello sfondo quando l'opzione 3 è selezionata per R.integer.config_letterboxBackgroundType. I valori inferiori a 0 o maggiori o uguali a 1 vengono ignorati e viene utilizzato 0.0 (trasparente) al loro posto.

Caso d'uso o contesto
Questa funzionalità non viene lanciata a causa di problemi di prestazioni esistenti. Gli OEM possono creare la propria implementazione di questa funzionalità, ma AOSP non gestirà eventuali bug.

Raggiungibilità e posizionamento

Questa sezione elenca tutte le impostazioni di configurazione applicate alla configurazione della finestra a livello di attività per l'accessibilità.

Nome Posizione Tipo Predefinito
config_letterboxIsHorizontalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se il riposizionamento dell'accessibilità orizzontale è abilitato per le app letterbox in modalità finestra a schermo intero.

Caso d'uso o contesto
Riposiziona un'app verticale a sinistra o a destra per facilitarne l'accesso.
config_letterboxHorizontalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.5
Descrizione
Configura la posizione orizzontale del centro della finestra dell'app letterbox.
0 corrisponde al lato sinistro dello schermo e 1 al lato destro.
Se il valore specificato è inferiore a 0 o superiore a 1, viene ignorato. Per la postura non a libro, viene utilizzata la posizione centrale (0.5). Per la postura del libro, viene utilizzata la posizione a sinistra (0.0).

Caso d'uso o contesto
Il valore predefinito è il centro per un'app letterbox verticale.
config_letterboxIsVerticalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se il riposizionamento della raggiungibilità verticale è attivato per le app letterbox in modalità finestra a schermo intero.

Caso d'uso o contesto
Riposiziona un'app orizzontale nella parte superiore o inferiore per facilitarne l'accesso.
config_letterboxVerticalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descrizione
Configura la posizione verticale del centro della finestra dell'app letterbox.
Il valore 0 corrisponde alla parte superiore dello schermo, mentre 1 a quella inferiore.
Se il valore specificato è inferiore a 0 o superiore a 1, viene ignorato. Per la modalità non da tavolo, viene utilizzata la posizione centrale (0.5). Per la postura sul tavolo, viene utilizzata la posizione superiore (0.0).

Caso d'uso o contesto
Configurato al centro nei dispositivi con schermo grande per un'app in formato letterbox orizzontale.
config_letterboxIsAutomaticReachabilityInBookModeEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se il posizionamento automatico orizzontale per la raggiungibilità in modalità libro è attivato per le app con letterbox in modalità finestra a schermo intero.

Caso d'uso o contesto
Consente a un'app con letterbox verticale di spostarsi da sinistra a destra quando un dispositivo pieghevole è in modalità libro.
config_letterboxBookModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descrizione
Configura la posizione orizzontale del centro della finestra dell'app letterbox quando è in modalità libro.
0 corrisponde al lato sinistro dello schermo e 1 al lato destro. Se il valore specificato è inferiore a 0 o superiore a 1, viene ignorato e viene utilizzata la posizione a sinistra (0.0).

Caso d'uso o contesto
Un moltiplicatore per la quantità di spostamento della posizione dell'app quando viene riposizionata in modalità libro.
config_letterboxDefaultPositionForBookModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Descrizione
Configura la posizione orizzontale predefinita della finestra dell'app letterbox quando l'accessibilità è attivata e un'app è a schermo intero in orientamento orizzontale del dispositivo e in modalità libro. Quando la raggiungibilità è attivata, la posizione può cambiare tra sinistra, centro e destra:
  • Opzione 0 - Sinistra
  • Opzione 1 - Centro
  • Opzione 2 - Destra
Se il valore specificato non rientra in questo intervallo, viene presupposta l'opzione 0 (a sinistra).

Caso d'uso o contesto
La posizione predefinita in cui l'app viene inserita in modalità libro.
config_letterboxTabletopModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descrizione
configura la posizione verticale del centro della finestra dell'app in letterbox quando è in modalità Tabletop.
Il valore 0 corrisponde alla parte superiore dello schermo, mentre 1 a quella inferiore. Se il valore specificato è inferiore a 0 o superiore a 1, viene ignorato e viene utilizzata la posizione 0.0.

Caso d'uso o contesto
Un moltiplicatore per la quantità di spostamento della posizione dell'app in un dispositivo pieghevole quando è in modalità tablet.
config_letterboxDefaultPositionForTabletopModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Descrizione
Configura la posizione verticale predefinita della finestra dell'app letterbox quando la raggiungibilità è attivata e un'app è a schermo intero in orientamento verticale del dispositivo e in posizione orizzontale. Quando l'accessibilità è attivata, la posizione può cambiare tra alto, centro e basso. Questa configurazione definisce quella predefinita:
  • Opzione 0 - In alto
  • Opzione 1 - Centro
  • Opzione 2 - In basso
Se il valore specificato non rientra in questo intervallo, viene presupposta l'opzione 0 (in alto).

Caso d'uso o contesto
La posizione predefinita in cui l'app viene posizionata in modalità tabletop.

Impostazioni

Questa sezione elenca tutte le impostazioni di configurazione per personalizzare e attivare le impostazioni delle proporzioni utente in Impostazioni > App > Proporzioni.

Nome Posizione Tipo Predefinito
config_appCompatUserAppAspectRatioSettingsIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se le impostazioni di override delle proporzioni per utente per app sono attive.

Caso d'uso o contesto
Attiva la funzionalità Impostazioni proporzioni in Impostazioni > App > Proporzioni.
config_appCompatUserAppAspectRatioFullscreenIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se l'opzione di override a schermo intero per app è attivata nelle impostazioni delle proporzioni utente.

Caso d'uso o contesto
Attiva l'opzione A schermo intero nella funzionalità impostazioni delle proporzioni utente.
Questa impostazione ignora le limitazioni di ridimensionamento, proporzioni e orientamento di un'app.
config_userAspectRatioOverrideEntries packages/apps/Settings/res/values/config.xml string-array Tutte le opzioni sono attive per impostazione predefinita.
Descrizione
Configura la schermata delle impostazioni delle proporzioni dell'app e le opzioni di override delle proporzioni dell'utente. Devono avere la stessa lunghezza e lo stesso ordine di config_userAspectRatioOverrideValues.
Se viene modificato, aggiorna anche la logica di backup e ripristino per scegliere il valore più vicino in UserAspectRatioBackupManager.java.

Caso d'uso o contesto
Mapping per le stringhe visualizzate in Impostazioni.
config_userAspectRatioOverrideValues packages/apps/Settings/res/values/config.xml integer-array Per impostazione predefinita vengono utilizzate tutte le stringhe AOSP.
Descrizione
Configura la schermata delle impostazioni delle proporzioni dell'app e le opzioni di override delle proporzioni dell'utente. Devono avere la stessa lunghezza e lo stesso ordine di config_userAspectRatioOverrideEntries. I valori devono corrispondere a PackageManager.UserMinAspectRatio.
Se modificato, aggiorna anche la logica di backup e ripristino per la scelta del valore più vicino in UserAspectRatioBackupManager.java.

Caso d'uso o contesto
Mapping delle opzioni al backend PackageManager.UserMinAspectRatio:
  • Predefinita dell'app - 0
  • Schermo diviso - 1
  • Proporzioni del display - 2
  • 4:3 - 3
  • 16:9 - 4
  • 3:2 - 5
  • Schermo intero - 6
Risorse disegnabili statiche con tema chiaro packages/apps/Settings/res/drawable/ic_app_aspect_ratio_<option>.xml vector Asset di dimensioni adatte ai dispositivi pieghevoli in formato orizzontale
Descrizione
Configura le risorse disegnabili disponibili:


Caso d'uso o contesto
Immagini statiche con tema chiaro sotto ogni opzione in Impostazioni > Informazioni app > Proporzioni.
Risorse disegnabili statiche con tema scuro packages/apps/Settings/res/drawable-night/ic_app_aspect_ratio_<option>.xml vector Asset di dimensioni adatte ai dispositivi pieghevoli in formato orizzontale
Descrizione
Configura le risorse disegnabili disponibili:


Caso d'uso o contesto
Immagini statiche con tema scuro in ogni opzione in Impostazioni > Informazioni app > Proporzioni.
Risorsa disegnabile dinamica
user_aspect_ratio_education.json		 packages/apps/Settings/res/raw/user_aspect_ratio_education.json JSON Asset dinamico di dimensioni adatte ai dispositivi pieghevoli in formato orizzontale
Descrizione
Configura un'illustrazione Lottie in UserAspectRatioAppsPageProvider.

Caso d'uso o contesto
Un'animazione sotto l'elenco delle app: Impostazioni > App > Proporzioni.

Istruzione

Questa sezione elenca tutte le impostazioni di configurazione per informare gli utenti sulle funzionalità di compatibilità delle app.

Nome Posizione Tipo Predefinito
config_letterboxIsEducationEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrizione
Configura se l'educazione al letterbox è attivata per le app a schermo intero con letterbox.

Caso d'uso o contesto
Vedi la Figura 1 per un caso d'uso dell'educazione al letterbox per le app a schermo intero.
config_letterboxIsRestartDialogEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Descrizione
Configura se la finestra di dialogo di riavvio esteso è attivata.

Caso d'uso o contesto
Vedi la figura 2 per un caso d'uso della finestra di dialogo di riavvio esteso.
config_letterboxIsReachabilityEducationEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Descrizione
Configura se è attivata l'istruzione aggiuntiva sull'accessibilità.

Caso d'uso o contesto
Vedi la figura 3 per un caso d'uso dell'istruzione sull'accessibilità.
config_isSizeCompatRestartButtonEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool true
Descrizione
Configura se il pulsante di riavvio della compatibilità delle dimensioni è attivato.

Caso d'uso o contesto
Un pulsante di riavvio per riavviare la configurazione delle app non ridimensionabili dopo le modifiche alle dimensioni della finestra, ad esempio quando si entra in modalità Split Screen o si ruota il display.
Consulta la figura 4 per un caso d'uso del pulsante di riavvio della compatibilità delle taglie.
config_letterboxRestartButtonHideTolerance frameworks/base/libs/WindowManager/Shell/res/values/config.xml Integer 100
Descrizione
Configura la tolleranza minima della percentuale dei limiti di attività all'interno del relativo task per nascondere il pulsante di riavvio della compatibilità delle dimensioni. I valori inferiori a 0 o superiori a 100 vengono ignorati.
100 è il valore predefinito in cui l'attività deve rientrare esattamente nell'attività per consentire di nascondere il pulsante di riavvio della compatibilità delle dimensioni. Il valore 0 indica che il pulsante di riavvio per la compatibilità delle dimensioni è sempre nascosto.

Caso d'uso o contesto
Utilizzato in dispositivi quasi quadrati per nascondere il pulsante di riavvio quando le app non ridimensionabili vengono ruotate dall'utente, ma il riavvio dell'app non migliora drasticamente l'interfaccia utente.

Le seguenti immagini mostrano i casi d'uso per l'overlay per l'istruzione:

Letterbox per le app a schermo intero

Figura 1. Letterbox per le app a schermo intero

Esempio di finestra di dialogo di riavvio esteso.

Figura 2. Finestra di dialogo di riavvio esteso

Un esempio di formazione sull&#39;accessibilità.

Figura 3. Formazione sulla raggiungibilità.

Un esempio del pulsante di riavvio della compatibilità delle dimensioni.

Figura 4. Pulsante di riavvio della compatibilità delle dimensioni.