대형 화면 앱 호환성 설정 가이드

이 페이지에서는 Android 대형 화면 앱 호환성 구성 오버레이에 관한 포괄적인 설정 가이드와 색인을 제공합니다.

디스플레이

이 섹션에는 디스플레이 수준 구성에 영향을 미치는 모든 구성 설정이 나열되어 있습니다.

이름 위치 유형 기본
ignoreOrientationRequest display_settings.xml config false
큰 화면 (>= 600dp)의 경우 true
설명
지정된 디스플레이에서 고정 방향 활동의 무료 사용자 회전을 사용 설정합니다.
예:
          <display-settings>
              <config identifier="0" />
              <display
                  name="<display's uniqueId>"
                  ignoreOrientationRequest="true"/>
          </display-settings>
        

사용 사례 또는 컨텍스트
디스플레이가 모든 앱의 요청된 방향을 무시하고 앱이 레터박스 처리됩니다.
모든 대형 화면 기기 및 Android Automotive OS에서 사용됩니다. 이는 Android 16 이상에서 smallestScreenWidthDp >= 600dp이 있는 모든 대형 화면 기기의 기본값입니다.
config_letterboxIsDisplayRotationImmersiveAppCompatPolicyEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
전체 화면에서 최적이 아닌 화면 방향으로 자동 회전되는 것을 방지하는 몰입형 앱의 회전 호환성 정책을 사용 설정합니다. 게임과 같은 몰입형 앱은 모든 방향에 최적화되어 있지 않은 경우가 많으며 회전하면 UX가 좋지 않을 수 있으므로 이 설정이 필요합니다. 또한 일부 게임은 게임플레이를 위해 센서를 사용하므로 자동 회전이 사용 설정된 경우 사용자가 실수로 이러한 회전을 트리거할 수 있습니다.
ignoreOrientationRequest이 사용 설정된 경우에만 적용됩니다.

사용 사례 또는 컨텍스트
몰입형 앱의 회전을 잠급니다.

가로세로 비율

이 섹션에는 활동 수준의 종횡비 창 구성에 영향을 미치는 모든 구성 설정이 나열되어 있습니다.

이름 위치 유형 기본
config_fixedOrientationLetterboxAspectRatio frameworks/base/core/res/res/values/config.xml Float 0.0
설명
고정 방향의 레터박싱 가로세로 비율을 구성합니다. 1.0 이하의 값은 무시됩니다.

사용 사례 또는 컨텍스트
대부분의 레터박스 앱에 적합한 기기 기본 가로세로 비율을 구성합니다. 일반적으로 정사각형 가로세로 비율에 더 가깝습니다.
config_letterboxIsSplitScreenAspectRatioForUnresizableAppsEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
크기 조절이 불가능한 앱의 기본 가로세로 비율로 화면 분할 가로세로 비율을 사용할지 여부를 구성합니다.

사용 사례 또는 컨텍스트
크기 조절이 불가능한 대부분의 앱은 세로형 캔디바 휴대전화 레이아웃을 예상합니다.
config_letterboxIsDisplayAspectRatioForFixedOrientationLetterboxEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
모든 레터박스 앱의 기본 종횡비로 디스플레이 종횡비를 사용할지 여부를 구성합니다.

사용 사례 또는 컨텍스트
부동 소수점 값을 구성하는 대신 디스플레이 종횡비를 프로그래매틱 방식으로 사용하는 구성

카메라

이 섹션에는 onCameraOpened 콜백 시 앱에 영향을 미치는 모든 구성 설정이 나열되어 있습니다. 이러한 설정은 디스플레이, 활동, 카메라 구성에 영향을 줄 수 있습니다.

이름 위치 유형 기본
config_isWindowManagerCameraCompatTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
카메라 버퍼와 앱 창 간의 방향 불일치로 인해 발생하는 문제에 카메라 호환성 처리를 사용 설정합니다.
여기에는 전체 화면에서 카메라에 연결된 고정 방향 활동을 강제로 회전하고 분할 화면에서 툴팁을 표시하는 것이 포함됩니다.
강제 회전 처리는 앱별 재정의 OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION로 사용 중지할 수 있습니다.

사용 사례 또는 컨텍스트
디스플레이를 앱에서 요청한 방향과 일치하도록 강제 회전하여 회전된 카메라 미리보기를 수정합니다.
config_isWindowManagerCameraCompatSplitScreenAspectRatioEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
카메라 호환성 처리가 사용 설정되고 활동이 전체 화면에서 카메라에 연결된 경우 활동이 화면 분할 비율을 사용하는지 구성합니다.

사용 사례 또는 컨텍스트
활동을 캔디바와 같은 비율로 레터박싱하여 늘어난 카메라 미리보기를 수정합니다.
일반적으로 가로 모드 기기에서 강제 회전 처리를 사용 설정 (config_isWindowManagerCameraCompatTreatmentEnabledcamera.enable_landscape_to_portrait)하여 활동의 세로 모드 캔디바와 같은 가로세로 비율을 시뮬레이션하여 늘어난 카메라 호환성 문제를 수정하는 데 사용됩니다.
camera.enable_landscape_to_portrait 시스템 속성 Bool false
설명
OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT 처리를 게이트합니다.
가로 모드 자연스러운 방향이 있는 카메라에서 카메라 출력이 잘리고 90도 회전되어 세로 모드 자연스러운 방향을 시뮬레이션하도록 강제합니다. 보고된 카메라 센서 방향이 기기의 모든 가로 모드 카메라에 대해 세로 모드입니다. 많은 앱이 이 상황을 처리하지 않으며 늘어난 이미지를 표시합니다.

사용 사례 또는 컨텍스트
카메라 HAL 회전 및 자르기 처리를 사용 설정합니다. 처리 방법에 관한 자세한 내용은 회전, 자르기, 크기 조절을 참고하세요.
빌드 시 mk 파일에 다음을 추가합니다. PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=true
이 처리를 위해서는 기기가 HAL에서 SCALER_ROTATE_AND_CROP를 지원해야 합니다. CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES을 참고하세요.
SCALER_ROTATE_AND_CROP의 HAL별 구현에 관한 안내는 metadata_definitions.xml를 참고하세요.

배경 및 UI

이 섹션에는 UI 맞춤설정을 위해 또는 활동 수준에서 레터박스 레이어의 표면에 적용되는 모든 구성 설정이 나열되어 있습니다.

이름 위치 유형 기본
config_letterboxActivityCornersRadius frameworks/base/core/res/res/values/config.xml Integer 0
설명
레터박스 모드로 표시된 활동의 모서리 반경을 구성합니다. 0 미만의 값은 기기 하단 모서리 반경 간의 최솟값과 동일한 반경으로 둥근 모서리를 사용 설정합니다. 기본값 0AppCompatLetterboxPolicy에서 모서리 둥글게 처리 로직을 사용 중지합니다.

사용 사례 또는 컨텍스트
일반적으로 실제 기기의 모서리 둥글게 처리와 일치하도록 구성됩니다.
config_letterboxIsEnabledForTranslucentActivities frameworks/base/core/res/res/values/config.xml Bool false
설명
반투명 활동 레터박싱의 특정 동작이 사용 설정되는지 구성합니다.

사용 사례 또는 컨텍스트
반투명 활동 또는 모달이 레터박싱되고 레터박싱된 활동 구성 내에서 제한되도록 합니다. 이 정책은 TransparentPolicy에 적용됩니다.
config_isCompatFakeFocusEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
분할 화면 재개 활동에 호환성 가짜 포커스를 전송할지 여부를 구성합니다.
일부 게임 엔진은 앱의 콘텐츠를 그리기 전에 포커스를 받기 위해 대기하는데, 이는 멀티 윈도우 모드에서 기본적으로 제공되지 않기 때문에 필요합니다.

사용 사례 또는 컨텍스트
분할 화면 모드로 전환한 후 검은색으로 표시되고 사용자가 앱을 탭하고 포커스를 맞춘 후에만 그려지는 앱의 Unity 게임 엔진에 호환성 처리를 적용하는 기존 플래그입니다.
config_letterboxBackgroundType frameworks/base/core/res/res/values/config.xml Integer 0
설명
레터박스 배경의 모서리 모양을 구성합니다.
  • 0 - R.color.config_letterboxBackgroundColor에 지정된 색상을 사용하는 단색 배경
  • 1 - 레터박스 처리된 애플리케이션의 R.attr.colorBackground에 지정된 색상입니다.
  • 2 - 레터박스 처리된 애플리케이션의 R.attr.colorBackgroundFloating에 지정된 색상입니다.
  • 3 - 흐림 효과가 적용된 배경화면 또는 어두운 스크림 config_letterboxBackgroundWallpaperBlurRadius 또는 config_letterboxBackgroundWallpaperDarkScrimAlpha 파라미터 중 하나 이상이 0보다 커야 합니다. 이 경우가 아니거나 흐림 반경이 제공되었지만 기기에서 흐림을 지원하지 않고 이 옵션이 선택된 경우 구현은 옵션 0로 기본 설정됩니다. 지정된 값이 이 범위를 벗어나면 옵션 0이 가정됩니다.


사용 사례 또는 컨텍스트
기존 성능 문제로 인해 이 기능이 출시되지 않습니다. OEM은 이 기능의 자체 구현을 만들 수 있지만 AOSP에서는 버그를 처리하지 않습니다.
config_letterboxBackgroundColor frameworks/base/core/res/res/values/config.xml Color @color/system_neutral1_1000
설명
다음 조건 중 하나가 true인 경우 레터박스 배경의 색상을 구성합니다.
  • R.integer.config_letterboxBackgroundType0 옵션이 선택되어 있습니다.
  • R.integer.config_letterboxBackgroundType1 옵션이 선택되어 있고 앱에 R.attr.colorBackground가 지정되어 있지 않습니다.
  • R.integer.config_letterboxBackgroundType2 옵션이 선택되어 있고 앱에 R.attr.colorBackgroundFloating가 지정되어 있지 않습니다.
  • R.integer.config_letterboxBackgroundType에 옵션 3이 선택되고 흐리게 처리가 요청되었지만 기기에서 지원되지 않거나 어두운 스크림 알파와 흐리게 처리 반경이 모두 제공되지 않습니다.


사용 사례 또는 컨텍스트
기존 성능 문제로 인해 이 기능이 출시되지 않습니다. OEM은 이 기능의 자체 구현을 만들 수 있지만 AOSP에서는 버그를 처리하지 않습니다.
config_letterboxBackgroundWallpaperBlurRadius frameworks/base/core/res/res/values/config.xml Dimen 38dp
설명
R.integer.config_letterboxBackgroundType에서 옵션 3의 흐림 반경을 구성합니다. 0보다 작은 값은 무시되고 0이 사용됩니다.

사용 사례 또는 컨텍스트
기존 성능 문제로 인해 이 기능이 출시되지 않습니다. OEM은 이 기능의 자체 구현을 만들 수 있지만 AOSP에서는 버그를 처리하지 않습니다.
config_letterboxBackgroundWallpaperDarkScrimAlpha frameworks/base/core/res/res/values/config.xml Float 0.54
설명
R.integer.config_letterboxBackgroundType에 옵션 3이 선택된 경우 배경화면 레터박스 배경 위에 표시되는 검은색 반투명 스크림의 알파를 구성합니다. 0 미만 또는 1 이상의 값은 무시되고 대신 0.0 (투명)이 사용됩니다.

사용 사례 또는 컨텍스트
기존 성능 문제로 인해 이 기능이 출시되지 않습니다. OEM은 이 기능의 자체 구현을 만들 수 있지만 AOSP에서는 버그를 처리하지 않습니다.

연결 가능성 및 포지셔닝

이 섹션에는 접근성을 위해 활동 수준 창 구성에 적용되는 모든 구성 설정이 나열되어 있습니다.

이름 위치 유형 기본
config_letterboxIsHorizontalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
전체 화면 창 모드에서 레터박스 처리된 앱에 가로 손쉬운 사용 재배치가 사용 설정되어 있는지 구성합니다.

사용 사례 또는 컨텍스트
더 쉽게 액세스할 수 있도록 세로 모드 앱을 왼쪽이나 오른쪽으로 재배치합니다.
config_letterboxHorizontalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.5
설명
레터박스 처리된 앱 창의 중심의 수평 위치를 구성합니다.
0는 화면의 왼쪽에 해당하고 1는 오른쪽에 해당합니다.
지정된 값이 0보다 작거나 1보다 크면 무시됩니다. 책 자세가 아닌 경우 중앙 위치 (0.5)가 사용됩니다. 책 자세의 경우 왼쪽 위치 (0.0)가 사용됩니다.

사용 사례 또는 컨텍스트
세로 레터박스 앱의 경우 기본적으로 중앙으로 설정됩니다.
config_letterboxIsVerticalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
전체 화면 창 모드에서 레터박스 앱에 세로 도달 범위 재배치가 사용 설정되는지 구성합니다.

사용 사례 또는 컨텍스트
더 쉽게 액세스할 수 있도록 가로 모드 앱을 상단 또는 하단으로 재배치합니다.
config_letterboxVerticalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
설명
레터박스 처리된 앱 창의 중심의 세로 위치를 구성합니다.
0은 화면의 상단에 해당하고 1은 하단에 해당합니다.
지정된 값이 0보다 작거나 1보다 크면 무시됩니다. 탁자 모드가 아닌 경우 중앙 위치 (0.5)가 사용됩니다. 테이블탑 자세의 경우 상단 위치 (0.0)가 사용됩니다.

사용 사례 또는 컨텍스트
가로 모드 레터박스 앱의 경우 대형 화면 기기에서 중앙으로 구성됩니다.
config_letterboxIsAutomaticReachabilityInBookModeEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
전체 화면 창 모드에서 레터박스 처리된 앱에 책 자세 자동 가로 도달 가능성 위치 지정이 사용 설정되어 있는지 구성합니다.

사용 사례 또는 컨텍스트
폴더블 기기가 책 자세일 때 세로 레터박스 처리된 앱이 왼쪽과 오른쪽 사이를 이동할 수 있습니다.
config_letterboxBookModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
설명
책 자세일 때 레터박스 처리된 앱 창의 중심의 가로 위치를 구성합니다.
0는 화면의 왼쪽에 해당하고 1는 오른쪽에 해당합니다. 지정된 값이 0보다 작거나 1보다 크면 무시되고 왼쪽 위치(0.0)가 사용됩니다.

사용 사례 또는 컨텍스트
책 자세로 재배치될 때 앱의 위치가 이동하는 정도의 승수입니다.
config_letterboxDefaultPositionForBookModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
설명
접근성이 사용 설정되고 앱이 가로 모드 기기 방향과 책 자세에서 전체 화면인 경우 레터박스 처리된 앱 창의 기본 가로 위치를 구성합니다. 접근성이 사용 설정되면 위치가 왼쪽, 중앙, 오른쪽 사이에서 변경될 수 있습니다.
  • 옵션 0 - 왼쪽
  • 옵션 1 - 가운데
  • 옵션 2 - 오른쪽
지정된 값이 이 범위를 벗어나면 옵션 0 (왼쪽)이 가정됩니다.

사용 사례 또는 컨텍스트
앱이 북 모드에서 배치되는 기본 위치입니다.
config_letterboxTabletopModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
설명
탁자 모드일 때 레터박스 처리된 앱 창의 중심의 세로 위치를 구성합니다.
0은 화면의 상단에 해당하고 1은 하단에 해당합니다. 지정된 값이 0보다 작거나 1보다 크면 무시되고 상단 위치 0.0이 사용됩니다.

사용 사례 또는 컨텍스트
테이블탑 자세일 때 폴더블 기기에서 앱의 위치가 이동하는 정도의 승수입니다.
config_letterboxDefaultPositionForTabletopModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
설명
접근성이 사용 설정되고 앱이 세로 기기 방향과 탁자 모드에서 전체 화면인 경우 레터박스 처리된 앱 창의 기본 세로 위치를 구성합니다. 접근성이 사용 설정된 경우 위치가 상단, 중앙, 하단으로 변경될 수 있습니다. 이 구성은 기본값을 정의합니다.
  • 옵션 0 - 상단
  • 옵션 1 - 가운데
  • 옵션 2 - 하단
지정된 값이 이 범위를 벗어나면 옵션 0 (상단)이 가정됩니다.

사용 사례 또는 컨텍스트
테이블 모드에서 앱이 배치되는 기본 위치입니다.

설정

이 섹션에는 설정 > > 화면 비율에서 사용자 화면 비율 설정을 맞춤설정하고 사용 설정하기 위한 모든 구성 설정이 나열되어 있습니다.

이름 위치 유형 기본
config_appCompatUserAppAspectRatioSettingsIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
앱별 사용자 가로세로 비율 재정의 설정이 사용 설정되는지 여부를 구성합니다.

사용 사례 또는 컨텍스트
설정 > > 가로세로 비율에서 가로세로 비율 설정 기능을 사용 설정합니다.
config_appCompatUserAppAspectRatioFullscreenIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
사용자 화면 비율 설정에서 앱별 전체 화면 재정의 옵션이 사용 설정되어 있는지 구성합니다.

사용 사례 또는 컨텍스트
사용자 화면 비율 설정 기능에서 전체 화면 옵션을 사용 설정합니다.
이 설정은 앱의 크기 조절 불가능 여부, 가로세로 비율, 방향 제한을 무시합니다.
config_userAspectRatioOverrideEntries packages/apps/Settings/res/values/config.xml string-array 모든 옵션은 기본적으로 사용 설정되어 있습니다.
설명
앱 화면 비율 설정 화면과 사용자 화면 비율 재정의 옵션을 구성합니다. 길이와 순서가 config_userAspectRatioOverrideValues와 같아야 합니다.
변경된 경우 UserAspectRatioBackupManager.java에서 가장 가까운 값을 선택하는 백업 및 복원 로직도 업데이트합니다.

사용 사례 또는 컨텍스트
설정에 표시되는 문자열의 매핑
config_userAspectRatioOverrideValues packages/apps/Settings/res/values/config.xml integer-array 모든 AOSP 문자열은 기본적으로 사용됩니다.
설명
앱 화면 비율 설정 화면과 사용자 화면 비율 재정의 옵션을 구성합니다. 길이와 순서가 config_userAspectRatioOverrideEntries와 같아야 합니다. 값은 PackageManager.UserMinAspectRatio에 상응해야 합니다.
변경된 경우 UserAspectRatioBackupManager.java에서 가장 가까운 값을 선택하는 백업 및 복원 로직도 업데이트합니다.

사용 사례 또는 컨텍스트
백엔드 PackageManager.UserMinAspectRatio 옵션의 매핑:
  • 앱 기본값 - 0
  • 화면 분할 - 1
  • 디스플레이 가로세로 비율 - 2
  • 4:3 - 3
  • 16:9 - 4
  • 3:2 - 5
  • 전체 화면 - 6
정적 밝은 테마 드로어블 packages/apps/Settings/res/drawable/ic_app_aspect_ratio_<option>.xml vector 가로형 폴더블 크기 애셋
설명
사용 가능한 드로어블을 구성합니다.


사용 사례 또는 컨텍스트
설정 > 앱 정보 > 화면 비율의 각 옵션 아래에 밝은 테마의 정적 이미지가 표시됩니다.
정적 어두운 테마 드로어블 packages/apps/Settings/res/drawable-night/ic_app_aspect_ratio_<option>.xml vector 가로형 폴더블 크기 애셋
설명
사용 가능한 드로어블을 구성합니다.


사용 사례 또는 컨텍스트
설정 > 앱 정보 > 화면 비율의 각 옵션 아래에 어두운 테마의 정적 이미지가 표시됩니다.
동적 드로어블
user_aspect_ratio_education.json
packages/apps/Settings/res/raw/user_aspect_ratio_education.json JSON 가로형 폴더블 크기의 동적 애셋
설명
UserAspectRatioAppsPageProvider에서 Lottie 삽화를 구성합니다.

사용 사례 또는 컨텍스트
앱 목록 아래의 애니메이션: 설정 > > 화면 비율

교육

이 섹션에는 앱 호환성 기능에 대해 사용자를 교육하기 위한 모든 구성 설정이 나열되어 있습니다.

이름 위치 유형 기본
config_letterboxIsEducationEnabled frameworks/base/core/res/res/values/config.xml Bool false
설명
레터박스 처리된 전체 화면 앱에 레터박스 교육이 사용 설정되어 있는지 구성합니다.

사용 사례 또는 컨텍스트
전체 화면 앱의 레터박스 교육 사용 사례는 그림 1을 참고하세요.
config_letterboxIsRestartDialogEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
설명
확장된 다시 시작 대화상자가 사용 설정되어 있는지 구성합니다.

사용 사례 또는 컨텍스트
확장된 다시 시작 대화상자의 사용 사례는 그림 2를 참고하세요.
config_letterboxIsReachabilityEducationEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
설명
도달 가능성에 관한 추가 교육을 사용 설정할지 여부를 구성합니다.

사용 사례 또는 컨텍스트
도달 가능성 교육의 사용 사례는 그림 3을 참고하세요.
config_isSizeCompatRestartButtonEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool true
설명
크기 호환성 다시 시작 버튼이 사용 설정되는지 여부를 구성합니다.

사용 사례 또는 컨텍스트
창 크기가 변경된 후 크기 조절이 불가능한 앱의 구성을 다시 시작하는 다시 시작 버튼(예: 화면 분할 모드로 전환하거나 디스플레이를 회전하는 경우)
크기 호환성 다시 시작 버튼의 사용 사례는 그림 4를 참고하세요.
config_letterboxRestartButtonHideTolerance frameworks/base/libs/WindowManager/Shell/res/values/config.xml Integer 100
설명
크기 호환성 다시 시작 버튼을 숨기기 위해 작업 내 활동 경계의 백분율의 최소 허용 오차를 구성합니다. 0보다 낮거나 100보다 높은 값은 무시됩니다.
100은 활동이 크기 호환성 다시 시작 버튼을 숨길 수 있도록 태스크 내에 정확히 맞아야 하는 기본값입니다. 0 값은 크기 호환성 다시 시작 버튼이 항상 숨겨져 있음을 의미합니다.

사용 사례 또는 컨텍스트
크기 조절이 불가능한 앱이 사용자에 의해 회전되지만 앱을 다시 시작해도 UI가 크게 개선되지 않는 경우 거의 정사각형 기기에서 다시 시작 버튼을 숨기는 데 사용됩니다.

다음 이미지는 교육 오버레이의 사용 사례를 보여줍니다.

전체 화면 앱의 레터박스 교육

그림 1. 전체 화면 앱의 레터박스 교육

확장된 다시 시작 대화상자의 예

그림 2. 연장된 다시 시작 대화상자

연결 가능성 교육의 예

그림 3. 도달 가능성 교육

크기 호환성 다시 시작 버튼의 예

그림 4. 크기 호환성 다시 시작 버튼