이 페이지에서는 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_isWindowManagerCameraCompatTreatmentEnabled 및 camera.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 미만의 값은 기기 하단 모서리 반경 간의 최솟값과 동일한 반경으로 둥근 모서리를 사용 설정합니다. 기본값 0는 AppCompatLetterboxPolicy에서 모서리 둥글게 처리 로직을 사용 중지합니다.사용 사례 또는 컨텍스트 일반적으로 실제 기기의 모서리 둥글게 처리와 일치하도록 구성됩니다. |
|||
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 |
| 설명 레터박스 배경의 모서리 모양을 구성합니다.
사용 사례 또는 컨텍스트 기존 성능 문제로 인해 이 기능이 출시되지 않습니다. OEM은 이 기능의 자체 구현을 만들 수 있지만 AOSP에서는 버그를 처리하지 않습니다. |
|||
config_letterboxBackgroundColor |
frameworks/base/core/res/res/values/config.xml |
Color |
@color/system_neutral1_1000 |
| 설명 다음 조건 중 하나가 true인 경우 레터박스 배경의 색상을 구성합니다.
사용 사례 또는 컨텍스트 기존 성능 문제로 인해 이 기능이 출시되지 않습니다. 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 (왼쪽)이 가정됩니다.사용 사례 또는 컨텍스트 앱이 북 모드에서 배치되는 기본 위치입니다. |
|||
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 (상단)이 가정됩니다.사용 사례 또는 컨텍스트 테이블 모드에서 앱이 배치되는 기본 위치입니다. |
|||
설정
이 섹션에는 설정 > 앱 > 화면 비율에서 사용자 화면 비율 설정을 맞춤설정하고 사용 설정하기 위한 모든 구성 설정이 나열되어 있습니다.
| 이름 | 위치 | 유형 | 기본 |
|---|---|---|---|
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 옵션의 매핑:
|
|||
| 정적 밝은 테마 드로어블 | 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. 크기 호환성 다시 시작 버튼