Guide de configuration de la compatibilité des applications avec les grands écrans

Cette page fournit un guide de configuration complet et un index des couches de configuration de la compatibilité des applications Android pour grand écran.

Écran

Cette section liste tous les paramètres de configuration qui affectent la configuration au niveau de l'affichage.

Nom Position Saisie Par défaut
ignoreOrientationRequest display_settings.xml config false
true pour les grands écrans (>= 600 dp)
Description
Permet aux utilisateurs de faire pivoter librement les activités à orientation fixe sur l'écran spécifié.
Exemple : 
          <display-settings>
              <config identifier="0" />
              <display
                  name="<display's uniqueId>"
                  ignoreOrientationRequest="true"/>
          </display-settings>

Cas d'utilisation ou contexte
L'écran ignore l'orientation demandée par toutes les applications, et l'application est encadrée.
Utilisé sur tous les appareils à grand écran et Android Automotive OS. Il s'agit de la valeur par défaut pour tous les appareils à grand écran avec smallestScreenWidthDp >= 600dp dans Android 16 et versions ultérieures.
config_letterboxIsDisplayRotationImmersiveAppCompatPolicyEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Active la règle de compatibilité de la rotation pour les applications immersives qui empêche la rotation automatique dans une orientation d'écran non optimale en mode plein écran. Cela est nécessaire, car les applications immersives, telles que les jeux, ne sont souvent pas optimisées pour toutes les orientations et peuvent offrir une mauvaise expérience utilisateur lorsqu'elles sont pivotées. De plus, certains jeux s'appuient sur des capteurs pour le gameplay. Les utilisateurs peuvent donc déclencher de telles rotations accidentellement lorsque la rotation automatique est activée.
S'applique uniquement si ignoreOrientationRequest est activé.

Cas d'utilisation ou contexte
Verrouille la rotation pour les applications immersives.

Format

Cette section liste tous les paramètres de configuration qui affectent la configuration de la fenêtre au niveau de l'activité pour le format.

Nom Position Saisie Par défaut
config_fixedOrientationLetterboxAspectRatio frameworks/base/core/res/res/values/config.xml Float 0.0
Description
Configure le format de la mise en boîte aux lettres pour l'orientation fixe. Les valeurs inférieures ou égales à 1.0 sont ignorées.

Cas d'utilisation ou contexte
Configure le format par défaut de l'appareil, qui fonctionne pour la plupart des applications au format letterbox. Généralement plus proche d'un format carré.
config_letterboxIsSplitScreenAspectRatioForUnresizableAppsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si le format d'écran partagé doit être utilisé comme format par défaut pour les applications non redimensionnables.

Cas d'utilisation ou contexte
La plupart des applications non redimensionnables s'attendent à une mise en page de téléphone au format Portrait.
config_letterboxIsDisplayAspectRatioForFixedOrientationLetterboxEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure l'utilisation du format d'affichage comme format par défaut pour toutes les applications encadrées.

Cas d'utilisation ou contexte
Configuration permettant d'utiliser le format d'affichage de manière programmatique au lieu de configurer une valeur flottante.

Appareil photo

Cette section liste tous les paramètres de configuration qui affectent les applications lors du rappel de onCameraOpened. Ces paramètres peuvent affecter l'affichage, l'activité et la configuration de la caméra.

Nom Position Saisie Par défaut
config_isWindowManagerCameraCompatTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Permet de traiter la compatibilité de l'appareil photo pour les problèmes causés par une orientation non concordante entre les tampons de l'appareil photo et une fenêtre d'application.
Cela inclut la rotation forcée des activités à orientation fixe connectées à la caméra en plein écran et affichant un info-bulle en écran partagé.
Le traitement de rotation forcée peut être désactivé par le forçage par application : OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Cas d'utilisation ou contexte
Corrige les aperçus de l'appareil photo en forçant la rotation de l'écran pour qu'elle corresponde à l'orientation demandée par l'application.
config_isWindowManagerCameraCompatSplitScreenAspectRatioEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si une activité utilise le format d'écran partagé lorsque le traitement de compatibilité de l'appareil photo est activé et que l'activité est connectée à l'appareil photo en plein écran.

Cas d'utilisation ou contexte
Corrige les aperçus de l'appareil photo étirés en ajoutant des bandes noires en haut et en bas de l'activité pour obtenir un format de type barre chocolatée.
Généralement utilisé avec le traitement de rotation forcée activé (config_isWindowManagerCameraCompatTreatmentEnabled et camera.enable_landscape_to_portrait) sur les appareils en mode paysage pour résoudre les problèmes de compatibilité de la caméra étirée en simulant un format de type candybar portrait pour l'activité.
camera.enable_landscape_to_portrait Propriété système Bool false
Description
 : permet d'activer le traitement OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT.
Force le recadrage et la rotation de 90 degrés de la sortie de l'appareil photo sur les appareils photo dont l'orientation naturelle est en mode Paysage pour simuler une orientation naturelle en mode Portrait. L'orientation du capteur de l'appareil photo signalée est "portrait" pour tous les appareils photo en mode paysage de l'appareil. De nombreuses applications ne gèrent pas cette situation et affichent des images étirées dans le cas contraire.

Cas d'utilisation ou contexte
Active le traitement de rotation et de recadrage de la HAL de l'appareil photo. Pour en savoir plus sur le traitement, consultez Rotation, recadrage, mise à l'échelle.
Ajoutez les éléments suivants à votre fichier mk au moment de la compilation : PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=true
Ce traitement nécessite que l'appareil prenne en charge SCALER_ROTATE_AND_CROP dans HAL. Consultez CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES.
Pour obtenir des conseils sur l'implémentation spécifique à HAL pour SCALER_ROTATE_AND_CROP, consultez metadata_definitions.xml.

Arrière-plan et UI

Cette section répertorie tous les paramètres de configuration appliqués à la surface de la couche letterbox pour la personnalisation de l'UI ou au niveau de l'activité.

Nom Position Saisie Par défaut
config_letterboxActivityCornersRadius frameworks/base/core/res/res/values/config.xml Integer 0
Description
Configure le rayon d'angle pour une activité présentée en mode Letterbox. Les valeurs inférieures à 0 permettent d'obtenir des angles arrondis avec un rayon égal au rayon minimal des angles inférieurs de l'appareil. Une valeur par défaut de 0 désactive la logique des angles arrondis dans AppCompatLetterboxPolicy.

Cas d'utilisation ou contexte
Généralement configuré pour correspondre aux angles arrondis de l'appareil physique.
config_letterboxIsEnabledForTranslucentActivities frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si le comportement spécifique pour le letterboxing des activités translucides est activé.

Cas d'utilisation ou contexte
Permet aux activités ou aux modaux translucides d'être letterboxés et contraints dans la configuration de l'activité letterboxée. La règle s'applique dans TransparentPolicy.
config_isCompatFakeFocusEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si l'envoi d'un faux focus de compatibilité pour les activités reprises en écran partagé est activé.
Cela est nécessaire, car certains moteurs de jeu attendent d'obtenir le focus avant de dessiner le contenu de l'application, qui n'est pas fourni par défaut dans les modes multifenêtre.

Cas d'utilisation ou contexte
Indicateur hérité permettant d'appliquer un traitement de compatibilité aux moteurs de jeu Unity pour les applications qui deviennent noires après l'activation du mode Écran partagé et qui ne sont dessinées qu'après que l'utilisateur a appuyé sur l'application et l'a sélectionnée.
config_letterboxBackgroundType frameworks/base/core/res/res/values/config.xml Integer 0
Description
Configure l'apparence des coins de l'arrière-plan de la letterbox :
  • 0 : arrière-plan uni utilisant la couleur spécifiée dans R.color.config_letterboxBackgroundColor.
  • 1 : couleur spécifiée dans R.attr.colorBackground pour l'application au format letterbox.
  • 2 : couleur spécifiée dans R.attr.colorBackgroundFloating pour l'application au format Letterbox.
  • 3 : fond d'écran avec un flou atténué ou un voile sombre. Au moins l'un des paramètres suivants doit être supérieur à 0 : config_letterboxBackgroundWallpaperBlurRadius ou config_letterboxBackgroundWallpaperDarkScrimAlpha. Si ce n'est pas le cas, ou si un rayon de flou est fourni, mais que le flou n'est pas pris en charge par l'appareil et que cette option est sélectionnée, l'implémentation est définie par défaut sur l'option 0. Si la valeur indiquée est en dehors de cette plage, l'option 0 est supposée.


Cas d'utilisation ou contexte
Cette fonctionnalité n'est pas lancée en raison de problèmes de performances existants. Les OEM peuvent créer leur propre implémentation de cette fonctionnalité, mais AOSP ne gérera aucun bug.
config_letterboxBackgroundColor frameworks/base/core/res/res/values/config.xml Color @color/system_neutral1_1000
Description :
Configure la couleur de l'arrière-plan de la letterbox si l'une des conditions suivantes est true :
  • L'option 0 est sélectionnée pour R.integer.config_letterboxBackgroundType.
  • L'option 1 est sélectionnée pour R.integer.config_letterboxBackgroundType et R.attr.colorBackground n'est pas spécifié pour l'application.
  • L'option 2 est sélectionnée pour R.integer.config_letterboxBackgroundType et R.attr.colorBackgroundFloating n'est pas spécifié pour l'application.
  • L'option 3 est sélectionnée pour R.integer.config_letterboxBackgroundType, et le flou est demandé, mais n'est pas pris en charge sur l'appareil, ou l'alpha du voile sombre et le rayon de flou ne sont pas fournis.


Cas d'utilisation ou contexte
Cette fonctionnalité n'est pas lancée en raison de problèmes de performances existants. Les OEM peuvent créer leur propre implémentation de cette fonctionnalité, mais AOSP ne gérera aucun bug.
config_letterboxBackgroundWallpaperBlurRadius frameworks/base/core/res/res/values/config.xml Dimen 38dp
Description
Configure le rayon de flou pour l'option 3 dans R.integer.config_letterboxBackgroundType. Les valeurs inférieures à 0 sont ignorées et 0 est utilisé.

Cas d'utilisation ou contexte
Cette fonctionnalité n'est pas lancée en raison de problèmes de performances existants. Les OEM peuvent créer leur propre implémentation de cette fonctionnalité, mais AOSP ne gérera aucun bug.
config_letterboxBackgroundWallpaperDarkScrimAlpha frameworks/base/core/res/res/values/config.xml Float 0.54
Description
Configure l'alpha d'un écran noir translucide affiché sur l'arrière-plan de la boîte aux lettres du fond d'écran lorsque l'option 3 est sélectionnée pour R.integer.config_letterboxBackgroundType. Les valeurs inférieures à 0 ou supérieures ou égales à 1 sont ignorées, et 0.0 (transparent) est utilisé à la place.

Cas d'utilisation ou contexte
Cette fonctionnalité n'est pas lancée en raison de problèmes de performances existants. Les OEM peuvent créer leur propre implémentation de cette fonctionnalité, mais AOSP ne gérera aucun bug.

Joignabilité et positionnement

Cette section liste tous les paramètres de configuration appliqués à la configuration de la fenêtre au niveau de l'activité pour l'accessibilité.

Nom Position Saisie Par défaut
config_letterboxIsHorizontalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si le repositionnement de l'accessibilité horizontale est activé pour les applications au format letterbox en mode plein écran.

Cas d'utilisation ou contexte
Repositionne une application en mode Portrait à gauche ou à droite pour faciliter l'accès.
config_letterboxHorizontalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.5
Description
Configure la position horizontale du centre de la fenêtre de l'application au format Letterbox.
0 correspond au côté gauche de l'écran et 1 au côté droit.
Si la valeur indiquée est inférieure à 0 ou supérieure à 1, elle est ignorée. Pour une posture autre que celle d'un livre, la position centrale (0.5) est utilisée. Pour la position du livre, la position de gauche (0.0) est utilisée.

Cas d'utilisation ou contexte
Par défaut, la position est centrée pour une application au format letterbox en mode Portrait.
config_letterboxIsVerticalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si le repositionnement vertical de l'accessibilité est activé pour les applications au format letterbox en mode fenêtré plein écran.

Cas d'utilisation ou contexte
Repositionne une application en mode paysage en haut ou en bas de l'écran pour faciliter l'accès.
config_letterboxVerticalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Description
Configure la position verticale du centre de la fenêtre de l'application au format Letterbox.
La valeur 0 correspond au haut de l'écran, et 1 au bas.
Si la valeur indiquée est inférieure à 0 ou supérieure à 1, elle est ignorée. Pour le mode autre que À plat, la position centrale (0.5) est utilisée. Pour la position sur table, la position supérieure (0.0) est utilisée.

Cas d'utilisation ou contexte
Configuré au centre des appareils à grand écran pour une application au format letterbox en mode paysage.
config_letterboxIsAutomaticReachabilityInBookModeEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si le positionnement automatique de l'accessibilité horizontale en mode livre est activé pour les applications au format letterbox en mode plein écran.

Cas d'utilisation ou contexte
Permet à une application au format letterbox en mode portrait de se déplacer de gauche à droite lorsqu'un appareil pliable est en mode livre.
config_letterboxBookModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Description
Configure la position horizontale du centre de la fenêtre de l'application en mode encadré lorsque l'appareil est en position livre.
0 correspond au côté gauche de l'écran et 1 au côté droit. Si la valeur indiquée est inférieure à 0 ou supérieure à 1, elle est ignorée et la position de gauche (0.0) est utilisée.

Cas d'utilisation ou contexte
Multiplicateur de la distance parcourue par l'application lorsqu'elle est repositionnée en mode livre.
config_letterboxDefaultPositionForBookModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Description
Configure la position horizontale par défaut de la fenêtre de l'application au format letterbox lorsque l'accessibilité est activée et qu'une application est en plein écran en orientation paysage et en position livre. Lorsque l'accessibilité est activée, la position peut changer entre gauche, centre et droite :
  • Option 0 – Gauche
  • Option 1 : centre
  • Option 2 – Droite
Si la valeur indiquée est en dehors de cette plage, l'option 0 (à gauche) est supposée.

Cas d'utilisation ou contexte
Position par défaut de l'application en mode livre.
config_letterboxTabletopModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Description
Configure la position verticale du centre de la fenêtre de l'application au format Letterbox en mode Table.
La valeur 0 correspond au haut de l'écran, et 1 au bas. Si la valeur indiquée est inférieure à 0 ou supérieure à 1, elle est ignorée et la position supérieure 0.0 est utilisée.

Cas d'utilisation ou contexte
Multiplicateur de la position de l'application sur un appareil pliable en mode Table.
config_letterboxDefaultPositionForTabletopModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Description
Configure la position verticale par défaut de la fenêtre de l'application au format letterbox lorsque l'accessibilité est activée et qu'une application est en plein écran en orientation portrait et en position tablette. Lorsque l'accessibilité est activée, la position peut être en haut, au centre ou en bas. Cette configuration définit celle par défaut :
  • Option 0 : en haut
  • Option 1 : centre
  • Option 2 : en bas
Si la valeur indiquée est en dehors de cette plage, l'option 0 (en haut) est supposée.

Cas d'utilisation ou contexte
Position par défaut de l'application en mode tablette.

Paramètres

Cette section liste tous les paramètres de configuration permettant de personnaliser et d'activer les paramètres de format de l'utilisateur dans Paramètres > Applications > Format.

Nom Position Saisie Par défaut
config_appCompatUserAppAspectRatioSettingsIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si les paramètres de remplacement du format par application sont activés.

Cas d'utilisation ou contexte
Active la fonctionnalité Paramètres du format dans Paramètres > Applications > Format.
config_appCompatUserAppAspectRatioFullscreenIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si l'option de remplacement du plein écran par application est activée dans les paramètres du format de l'utilisateur.

Cas d'utilisation ou contexte
Active l'option Plein écran dans la fonctionnalité Paramètres du format de l'utilisateur.
Ce paramètre ignore les restrictions d'une application concernant la non-redimensionnabilité, le format et l'orientation.
config_userAspectRatioOverrideEntries packages/apps/Settings/res/values/config.xml string-array Toutes les options sont activées par défaut.
Description
Configure l'écran des paramètres du format de l'application et les options de remplacement du format par l'utilisateur. Doit avoir la même longueur et le même ordre que config_userAspectRatioOverrideValues.
If changed, also update the Backup & Restore logic for choosing the closest value in UserAspectRatioBackupManager.java.

Use case or context
Mappings for the strings displayed in Settings.
config_userAspectRatioOverrideValues packages/apps/Settings/res/values/config.xml integer-array Toutes les chaînes AOSP sont utilisées par défaut.
Description
Configure l'écran des paramètres du format de l'application et les options de remplacement du format par l'utilisateur. Doit avoir la même longueur et le même ordre que config_userAspectRatioOverrideEntries. Les valeurs doivent correspondre à PackageManager.UserMinAspectRatio.
Si la valeur est modifiée, mettez également à jour la logique de sauvegarde et de restauration pour choisir la valeur la plus proche dans UserAspectRatioBackupManager.java.

Cas d'utilisation ou contexte
Mappages des options vers le backend PackageManager.UserMinAspectRatio :
  • Par défaut de l'application : 0
  • Écran partagé : 1
  • Format d'affichage : 2
  • 4:3 – 3
  • 16:9 : 4
  • 3:2 – 5
  • Plein écran : 6
Drawables statiques sur le thème clair packages/apps/Settings/res/drawable/ic_app_aspect_ratio_<option>.xml vector Composants au format paysage pour les appareils pliables
Description
Configure les drawables disponibles :


Cas d'utilisation ou contexte
Images statiques sur le thème clair sous chaque option dans Paramètres > Infos sur l'appli > Format.
Drawables statiques à thème sombre packages/apps/Settings/res/drawable-night/ic_app_aspect_ratio_<option>.xml vector Composants au format paysage pour les appareils pliables
Description
Configure les drawables disponibles :


Cas d'utilisation ou contexte
Images statiques avec thème sombre sous chaque option dans Paramètres > Infos sur l'appli  > Format.
Élément graphique dynamique
user_aspect_ratio_education.json		 packages/apps/Settings/res/raw/user_aspect_ratio_education.json JSON Composant dynamique au format paysage pour les appareils pliables
Description
Configure une illustration Lottie dans UserAspectRatioAppsPageProvider.

Cas d'utilisation ou contexte
Animation sous la liste des applications : Paramètres > Applications > Format.

Éducation

Cette section répertorie tous les paramètres de configuration permettant d'informer les utilisateurs sur les fonctionnalités de compatibilité des applications.

Nom Position Saisie Par défaut
config_letterboxIsEducationEnabled frameworks/base/core/res/res/values/config.xml Bool false
Description
Configure si l'éducation au letterboxing est activée pour les applications plein écran au format letterbox.

Cas d'utilisation ou contexte
Consultez la figure 1 pour un cas d'utilisation de l'éducation au letterboxing pour les applications plein écran.
config_letterboxIsRestartDialogEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Description
Configure si la boîte de dialogue de redémarrage étendu est activée.

Cas d'utilisation ou contexte
Consultez la figure 2 pour un cas d'utilisation de la boîte de dialogue de redémarrage étendu.
config_letterboxIsReachabilityEducationEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Description
Configure si des informations supplémentaires sur l'accessibilité sont activées.

Cas d'utilisation ou contexte
Consultez la figure 3 pour un cas d'utilisation des informations sur l'accessibilité.
config_isSizeCompatRestartButtonEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool true
Description
Configure si le bouton de redémarrage de la compatibilité de taille est activé.

Cas d'utilisation ou contexte
Bouton de redémarrage pour redémarrer la configuration des applications non redimensionnables après un changement de taille de la fenêtre, par exemple lors du passage en mode écran partagé ou de la rotation de l'écran.
Consultez la figure 4 pour découvrir un cas d'utilisation du bouton de redémarrage de compatibilité de taille.
config_letterboxRestartButtonHideTolerance frameworks/base/libs/WindowManager/Shell/res/values/config.xml Integer 100
Description
Configure la tolérance minimale du pourcentage de limites d'activité dans sa tâche pour masquer le bouton de redémarrage de compatibilité de taille. Les valeurs inférieures à 0 ou supérieures à 100 sont ignorées.
100 est la valeur par défaut où l'activité doit s'insérer exactement dans la tâche pour permettre de masquer le bouton de redémarrage de la compatibilité de taille. La valeur 0 signifie que le bouton de redémarrage de compatibilité de taille est toujours masqué.

Cas d'utilisation ou contexte
Utilisé sur les appareils presque carrés pour masquer le bouton de redémarrage lorsque les applications non redimensionnables sont pivotées par l'utilisateur, mais que le redémarrage de l'application n'améliorera pas radicalement l'UI.

Les images suivantes montrent des cas d'utilisation de la superposition éducative :

Letterboxing pour les applications en plein écran

Figure 1. Letterboxing pour les applications en plein écran

Exemple de boîte de dialogue de redémarrage étendu.

Figure 2. Boîte de dialogue de redémarrage étendu

Exemple d&#39;information sur la joignabilité.

Figure 3. Formation sur la joignabilité.

Exemple de bouton de redémarrage de la compatibilité de taille.

Figure 4. Bouton de redémarrage du mode de compatibilité de taille.