이 페이지는 Cloud Translation API를 통해 번역되었습니다.

기기 호환성 모드

Android는 방향이나 동작을 선언하는 앱을 위해 호환성 모드를 활성화합니다. 크기 조정 가능 여부 제한 호환성 모드를 사용하면 대형 화면 기기와 폴더블 플립형 휴대전화를 지원하지만 사용성이 최적화되지 않았습니다.

앱별 재정의를 사용하면 기기 제조업체에서 다음을 변경할 수 있습니다. 앱이 중단되지 않도록 하기 위한 앱 동작 확인할 수 있습니다.

참조 기기

다음 기기에서는 비정상적인 동작으로 인해 앱별로 재정의해야 할 수 있습니다. 앱에서 제대로 지원하지 않는 구성이나 구성을 제거해야 합니다.

태블릿: Pixel Tablet과 같은 일부 태블릿의 자연스러운 방향은 가로 모드입니다. 기기가 자연스러운 방향이 될 때 Display#getRotation() 반환 Surface.ROTATION_0. 앱에서 ROTATION_0가 세로 모드라고 가정하면 앱 레이아웃과 카메라 미리보기가 기기 디스플레이와 일치하지 않을 수 있습니다.
가로 모드 폴더블: Pixel Fold와 같은 일부 폴더블 기기는 접었을 때 세로 방향이고 펼쳤을 때 가로 방향입니다. 앱에서 펼쳐진 방향을 세로 모드라고 가정하면 깜박임 루프나 레이아웃 문제가 발생할 가능성이 높습니다.
플립형 플립형 휴대전화: 플립형 휴대전화를 펼친 모습은 일반적으로 세로 모드입니다. 방향을 설정할 수 있습니다. 하지만 접었을 때 휴대전화는 보통 작은 디스플레이가 사용할 수 있습니다. 앱은 다양한 유형의 콘텐츠를 식별하고 디스플레이 방향입니다.

일반적인 호환성 문제

앱의 호환성 문제가 가장 자주 발생하는 이유는 앱 방향 때문입니다. 크기 조절 가능 여부 및 가로세로 비율 제한, 잘못된 처리 카메라 미리보기 방향, 오용된 API 등이 있습니다

레터박스

레터박스는 앱을 화면 중앙에 배치하거나 대형 화면에서는 한쪽 또는 다른 쪽으로 하여 간편하게 액세스할 수 있습니다. 매트 (단색 막대 또는 블러 처리된 배경화면)을 사용하여 측면이나 상단을 따라 사용되지 않는 디스플레이 영역을 채우고 앱 하단에 표시됩니다.

레터박스는 대형 화면 기기에서 자주 발생합니다. 기기 디스플레이의 가로세로 비율은 일반적으로 표준 가로세로 비율과 다릅니다. 포함되어 있습니다.

그림 1. 가로 모드 태블릿 및 폴더블에서 레터박스 처리된 세로 모드 방향으로 제한된 앱

문제

앱이 모든 디스플레이 구성을 지원하지는 않습니다. 앱이 다음과 같은 문제를 해결했기 때문입니다. 고정된 가로세로 비율이거나 크기를 조절할 수 없습니다.

앱 방향과 크기 조절 가능 여부를 제어하는 구성 설정은 다음과 같습니다. 있습니다.

screenOrientation: 고정된 방향을 지정합니다. 앱일 수 있습니다. 또한 앱은 런타임 시 Activity#setRequestedOrientation().
resizeableActivity: 시스템이 다양한 크기의 창에 맞게 앱 크기를 조절할 수 있습니다. Android 11 (API 수준) 30) 이하는 앱에서 멀티 윈도우 모드를 지원하는지 지정합니다. 사용 설정됨 Android 12 (API 수준 31) 이상에서는 앱이 작은 화면 (sw 600dp 미만)의 멀티 윈도우 모드. Android 12 및 앱이 대형 화면 (sw 600dp 이상)에서 멀티 윈도우 모드를 지원합니다. 이 설정에 관계없이
maxAspectRatio: 최대 가로세로 비율을 지정합니다. 할 수 있습니다. resizeableActivity가 false로 설정된 앱만 maxAspectRatio로 설정합니다.
minAspectRatio: 최소 가로세로 비율을 지정합니다. 할 수 있습니다. resizeableActivity가 false로 설정된 앱만 minAspectRatio로 설정합니다.

세로 모드 방향으로 제한된 앱은 가로 모드 기기에서 사용할 수 없습니다.

최적화

앱은 모든 기기와 멀티 윈도우 모드 디스플레이 방향을 지원해야 하며 있습니다. 앱에서 모든 방향 및 고정된 가로세로 비율 제한을 삭제하세요. 앱 매니페스트 파일에 있습니다.

앱이 모든 기기 방향을 지원합니다.

호환성 해결 방법

방향이나 가로세로 비율이 고정된 앱이 창에서 실행되는 경우 앱이 창 크기나 방향을 직접 지원하지 않는 경우 연속성을 유지하기 위해 앱에 레터박스 처리합니다.

Android 12 (API 수준 31)부터 12L (API 수준 32)까지 플랫폼은 레터박스 앱에 다양한 개선사항을 적용합니다. 기기 UI 개선사항을 구현합니다. 이때 광고주가 추가 작업을 할 개선해야 합니다.

Android 12 (API 수준 31)에서는 다음과 같은 미학적 개선사항을 도입합니다. 기기 제조업체에서 구성할 수 있습니다.

둥근 모서리: 앱 창의 모서리에 더 세련된 모양이 적용됩니다.
시스템 표시줄 투명도: 화면에 오버레이되는 상태 및 탐색 메뉴 앱은 반투명하여 막대의 아이콘이 항상 레터박스 배경을 사용합니다.
구성 가능한 가로세로 비율: 앱의 가로세로 비율을 조정할 수 있습니다. 앱 디자인을 개선할 수 있습니다.

그림 2. UI 개선사항이 있는 레터박스 처리된 앱

12L(API 수준 32)에서는 다음과 같은 기능 개선사항을 추가합니다.

구성 가능한 포지셔닝: 대형 화면에서 기기 제조업체는 앱을 디스플레이의 왼쪽이나 오른쪽에 배치하여 더욱 쉽게 상호 작용할 수 있습니다
새롭게 디자인된 다시 시작 버튼: 기기 제조업체는 사용자가 다시 시작 버튼을 크기 호환성 모드의 새로운 디자인 버튼 사용자가 더 잘 알아볼 수 있습니다.

Android 13 (API 수준 33)에는 레터박스 처리된 앱이 화면에 표시되거나 화면 분할 모드의 레터박스를 포함하는 경우:

그림 3. 사용자 교육 대화상자가 있는 레터박스 처리된 앱

크기 호환성 모드

크기 호환성 모드는 다시 시작 컨트롤이 포함된 레터박스입니다. 이 컨트롤을 사용하면 사용자가 앱을 다시 시작하고 디스플레이를 다시 그릴 수 있습니다. Android 호출 크기 호환성 모드입니다. 사용자가 디스플레이 컨테이너로 이동하는 경우 시스템은 앱의 크기를 조정하여 기기 화면을 최소 1개의 측정기준을 사용해야 합니다.

크기 호환성 모드를 트리거할 수 있는 기기 설정 변경사항은 다음과 같습니다.

기기 회전
폴더블 기기 접기 또는 펼치기
전체 화면 디스플레이 모드와 화면 분할 디스플레이 모드 간 변경

문제

크기 호환성 모드는 일반적으로 가로 세로 비율이며, 이러한 화면은 자동으로 크기를 조절할 수 없습니다.

앱이 크기를 조절할 수 있는 것으로 간주되며 크기가 조정되지 않습니다. 다음 기준 중 하나라도 충족하는 경우 호환성 모드:

resizeableActivity="true"로 크기를 조절할 수 있습니다.
PIP 모드를 지원합니다.
삽입됩니다.
다음을 통해 FORCE_RESIZE_APP 앱별 재정의가 적용됨 기기 제조업체 (앱에서 설정한 속성은 무시됨)

앱이 어떤 조건도 충족하지 않으면 크기를 조절할 수 있으며 크기 호환성 모드로 배치할 수 있습니다.

크기를 조절할 수 없는 앱이 멀티 윈도우 모드에서 비정상 종료됩니다.

최적화

앱은 모든 디스플레이 크기를 지원해야 합니다. 다음과 같이 앱의 크기를 조절할 수 있도록 합니다. <activity>의 android:resizeableActivity 속성 또는 <application> 요소를 true 앱 매니페스트를 참조하세요. 앱의 반응형/적응형 레이아웃을 디자인합니다. 자세히 알아보기 자세한 내용은 다양한 화면 크기 지원 멀티 윈도우 지원.

앱이 모든 창 크기에서 작동합니다.

호환성 해결 방법

Android는 시스템에서 크기를 결정할 때 앱을 크기 호환성 모드로 전환합니다. 앱의 크기를 조정하여 레터박스 처리된 앱의 표시 방식을 개선할 수 있습니다. 디스플레이 창을 한 개 이상 표시해서는 안 됩니다. 시스템에 다시 시작 컨트롤이 표시됩니다. 이는 앱 프로세스를 다시 만들어 활동을 다시 만들고 디스플레이. 프로세스 및 스레드 개요도 참고하세요.

가로 모드 방향으로 레터박스 처리된 세로 모드 전용 앱이 다시 시작 컨트롤로 재조정됩니다.

깜박이는 루프

앱이 모든 디스플레이 방향을 지원하지 않는 경우 반복적으로 구성 변경이 발생할 때 새로운 방향을 요청하여 디스플레이가 깜박이거나 앱이 끊임없이 회전하도록 하는 무한 루프입니다.

문제

Android 12 (API 수준 31) 이상에서 기기 제조업체는 기기에서 앱이 지정한 방향 제한을 무시하고 대신 호환성 모드를 적용합니다. 예를 들어 폴더블 기기는 활동의 android:screenOrientation="portrait" 활동이 기기의 가로 모드 태블릿 크기로 표시될 때 있습니다.

앱의 방향 제한이 무시되면 앱이 프로그래매틱 방식으로 표시될 수 있습니다. 다음을 호출하여 방향을 설정합니다. Activity#setRequestedOrientation() 호출 앱이 구성 변경을 처리하지 않는 경우 앱 다시 시작을 트리거합니다( 구성 변경 처리). 그런 다음 다시 시작하면 앱의 방향 제한이 다시 무시되고 앱이 반복됨 setRequestedOrientation() 호출이 앱 다시 시작을 트리거합니다. 그 자체가 영구적인 루프에 돌입합니다.

이 문제가 발생할 수 있는 또 다른 방법은 자연스러운 방향 (일반적인 방향 가로 모드 (즉, Display#getRotation() 반환 기기가 가로 모드인 경우 Surface.ROTATION_0 입니다. 지금까지 앱은 Display.getRotation() = Surface.ROTATION_0가 기기가 세로 모드 방향임을 의미한다고 가정했지만 실제로는 그렇지 않습니다. 항상 표시됩니다(예: 일부 폴더블 기기의 내부 화면 및 일부 태블릿에서 사용할 수 있습니다.

폴더블 내부 디스플레이에서 가로 모드 방향의 앱은 다음을 확인할 수 있습니다. 화면 회전, ROTATION_0 값 수신, 자연스러운 방향 가정 세로 모드일 때 setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT 앱 레이아웃을 재구성하는 ). 앱이 다시 시작된 후 (가로 모드) 다시 화면 회전을 확인하고 ROTATION_0, 통화 setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT), 무한 루프를 계속합니다.

세로 모드 디스플레이의 가로 모드 전용 앱은 `Activity#setRequestedOrientation()`을 반복적으로 호출합니다.

최적화

앱은 다음 작업을 실행해서는 안 됩니다.

다음에서 Activity#setRequestedOrientation()를 사용하여 기본 방향을 설정합니다. onCreate() 메서드를 호출할 수 있습니다. 처리되지 않은 구성 변경으로 인해 예기치 않게 트리거됨
기기의 자연스러운 방향(ROTATION_0)이 세로 모드라고 가정합니다.
현재 창 크기와 관련 없는 신호에 따라 방향을 설정합니다. Display#getRotation()로서 FoldingFeature 또는 지원 중단된 API.

앱이 구성 변경을 처리하고 방향을 제한하지 않으므로 깜박이는 루프에 들어가지 않습니다.

호환성 해결 방법

Android는 다음에서 Activity#setRequestedOrientation() 호출을 무시합니다. 상황:

활동이 이전 메서드 호출에서 이미 다시 시작되었거나 카메라 호환성 강제 회전 처리가 사용 설정되었습니다 (카메라 미리보기를 참조하세요.

기기 제조업체는 OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
활동이 1초에 세 번 이상 방향을 요청했으며, 루프가 발생했음을 나타냅니다. 루프의 두 요청 중 Android는 앱 디스플레이 영역을 극대화합니다

기기 제조업체는 OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED

카메라 미리보기

카메라 앱의 카메라 미리보기 (또는 뷰파인더)가 잘못 정렬되거나 왜곡될 수 있음 태블릿, 노트북, 폴더블 디스플레이에서

문제

Android 호환성 정의 문서에는 카메라 이미지 센서는 '카메라의 긴 쪽이 360도 회전하도록 화면의 긴 크기에 맞춥니다."

앱에서는 기기 방향과 카메라 센서 방향이 세로 모드 — 표준 휴대전화에서는 합리적인 가정입니다. 하지만 태블릿과 노트북, 카메라 센서의 자연스러운 방향은 가로 모드입니다. 또한 폴더블과 같은 새로운 폼 팩터에는 여러 카메라 센서가 있을 수 있습니다.

앱이 예상하지 않는 카메라 방향으로 활동을 시작 또는 다른 카메라나 기기 화면 (폴더블용) 간에 전환하면 발생할 수 있으며 카메라 미리보기가 잘못 정렬되거나 왜곡됩니다.

대형 화면 폴더블에서 카메라 미리보기가 잘못 정렬되고 왜곡됩니다.

최적화

카메라 앱은 기기 방향과 카메라를 올바르게 식별하고 관리해야 합니다. 센서 방향을 사용하여 올바르게 정렬되고 조정된 카메라 미리보기를 표시합니다. 앱은 기기 회전, 센서 회전, 화면 또는 창을 계산해야 합니다. 선택한 다음 결과를 카메라 미리보기에 적용합니다. 자세한 내용은 카메라 미리보기 및 카메라 소개를 참고하세요. 뷰파인더

카메라 미리보기가 모든 기기 방향에서 올바르게 정렬되고 조정됩니다.

호환성 해결 방법

Display#getRotation()일 때 기기는 자연스러운 방향입니다. 은 Surface.ROTATION_0를 반환합니다. 시스템에서 CameraCharacteristics.SENSOR_ORIENTATION 방향을 전환할 수 있습니다. Android는 이미지의 세로 창을 자연스러운 방향의 세로 모드 제한 앱을 사용할 수 있습니다. 대부분의 앱에서 기대하는 부분입니다. 또한 Android는 센서 방향은 가로 모드이고 카메라 미리보기는 세로 모드입니다. 특정 해결 방법은 다음과 같습니다.

세로 모드 제한 앱의 카메라 미리보기 강제 회전: 앱 세로 모드 방향으로 제한됩니다. 기기의 자연스러운 방향을 예상합니다. 카메라 센서 방향은 세로 모드로 설정합니다. 하지만 Android 12에서는 (API 수준 31) 이상에서는 다음과 같은 경우 앱이 여러 기기 방향으로 실행될 수 있습니다. 기기 제조업체는 방향 사양을 무시합니다.

세로 모드 제한 앱이 카메라에 연결되면 Android가 강제로 앱을 회전하여 앱 세로 모드 창을 자연스러운 기기의 방향입니다.

일부 태블릿 (참조 기기 참고)에서 앱 세로 모드 창이 전체 화면 세로 모드로 회전하여 기기의 자연스러운 방향입니다. 앱이 강제 종료 후 전체 화면을 차지합니다. 있습니다.

태블릿: 세로 모드 제한 앱을 강제로 회전합니다.

폴더블의 가로 모드 내부 화면 (참고 자료 참고) ) 세로 모드 전용 활동이 다음과 같이 회전합니다. 펼쳐진 자연스러운 방향에 맞춥니다. 이 앱은 레터박스 처리됩니다.

폴더블: 세로 모드 제한 앱을 강제로 회전합니다. 앱은 레터박스 처리되어 있습니다.

참고: 앱이 반응형이며 사용할 수 있습니다.
내부 전면 카메라 자르기: 일부 기기의 내부 전면 카메라 센서가 폴더블이 가로 모드 방향입니다. 인코더-디코더 아키텍처를 폴더블 내부 디스플레이의 카메라 미리보기, Android에서 내부 전면을 자름 센서가 반대편 뷰를 캡처하도록 (가로 모드) 카메라 시야 변경할 수 있습니다.
카메라 미리보기 강제 새로고침: 시스템이 활동을 순환합니다. 메서드 onStop() 및 onStart() (기본값) 또는 onPause() 및 onResume()( OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE 강제로 회전 후 카메라 미리보기가 표시됩니다.
가로세로 비율 조정: 시스템에서 가로 세로 비율을 동적으로 변경합니다. 카메라 미리보기를 더 높은 최소 가로세로 비율로 강제 회전했습니다. 카메라 미리보기가 적절히 조정되는지 확인합니다.

앱이 카메라 미리보기를 처리하는 경우 앱 개발자는 이러한 해결 방법을 재정의할 수 있습니다. 있습니다. 앱별 재정의를 참고하세요.

일반적으로 오용되는 API

Android가 멀티 윈도우 모드 및 기존 API가 지원 중단되고 모든 디스플레이 크기 및 기기 양식에서 작동하는 최신 API 있습니다. 하지만 지원 중단된 API는 이전 버전과 함께 호환성을 제공합니다

일부 View API는 적합하지 않을 수 있는 특수한 용도로 설계됨 이해할 수 있습니다

문제

개발자는 지원 중단된 Display API를 계속 사용하고 API가 기기 디스플레이 영역 경계 대신 앱 경계를 반환합니다. 개발자 실수로 특수 목적의 View API를 사용하여 일반 디스플레이 측정항목을 가져옴 결과적으로 앱 창 이후에 UI 요소의 위치를 변경할 때 계산이 잘못됩니다. 레이아웃 문제가 발생할 수 있습니다.

지원 중단되고 일반적으로 오용되는 Display API:

자세한 내용은 멀티 윈도우 지원.

오용되는 View API:

지원 중단된 API가 앱 경계를 잘못 계산합니다. 앱 콘텐츠가 화면에서 사라집니다.

최적화

UI 요소를 배치하는 데 실제 디스플레이 크기를 사용하지 마세요. 다음을 포함하여 WindowMetrics 기반의 API에 앱을 배포합니다. WindowManager API:

플랫폼:
- getCurrentWindowMetrics()
- getMaximumWindowMetrics()
제트 추진:
- WindowMetricsCalculator#computeCurrentWindowMetrics()
- WindowMetricsCalculator#computeMaximumWindowMetrics()

API에서 앱 창 측정항목을 올바르게 계산합니다.

호환성 해결 방법

두 재정의는 지원 중단된 Display API와 오용된 View API를 다음과 같이 조정합니다. 앱 경계를 반환합니다. Display의 ALWAYS_SANDBOX_DISPLAY_APIS API OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS View API용 ALWAYS_SANDBOX_DISPLAY_APIS은(는) 기본적으로 다음 항목에도 적용됩니다. 크기 호환성 모드 자격요건을 충족하는 앱

투명한 활동

투명한 활동은 예:

<style name="Transparent" parent="AppTheme">
    <item name="android:windowIsTranslucent">true</item>
    <item name="android:windowBackground">@android:color/transparent</item>
</style>

대화상자와 관련된 테마(예: Theme.MaterialComponents.Dialog)는 활동을 투명하게 만드는 스타일을 포함합니다.

투명한 활동은 사용 가능한 디스플레이 공간을 모두 차지하지 않기 때문에 사용할 수 있는 디스플레이 영역이 디스플레이 광고 크기에 따라 달라질 수 있으므로 기기 회전, 기기 접기 및 펼치기, 멀티 윈도우 모드를 지원합니다.

문제

투명한 활동은 첫 번째 불투명 활동의 경계를 준수해야 합니다. 할 수 있습니다. 하지만 활동 중 일부는 트램펄린 (다른 활동을 실행한 후 사라지는 활동) 및 따라서 시스템은 트램펄린 활동의 경계를 투명한 권한 대화상자 활동을 시작했습니다.

활동이 트램펄린에서 시작되었기 때문에 대화상자가 잘못 배치되었습니다.

최적화

투명한 활동은 최상위 불투명에서 제약 조건을 상속받습니다. 활동이 있을 수 있습니다. 불투명 활동은 다음과 같아야 합니다. 투명한 활동의 전체 수명 주기에서 사용할 수 있음 파괴할 수 있습니다. 따라서 트램펄린 활동.

트램펄린 활동이 권한 요청을 실행하면 사용자는 권한 대화상자가 표시됩니다. 트램펄린 활동이 제거하기 전에 취소할 수 있으며 대화상자 활동의 크기와 위치가 계산되었을 수도 있습니다. 오답입니다.

앱은 항상 남아 있는 활동에서 권한 요청을 실행해야 함 사용자가 권한을 결정할 때까지 계속 표시됩니다.

둥근 모서리

백그라운드를 지정하는 스타일로 인해 활동이 투명할 수 있음 사용할 수 있는 빈 공간을 채우지 못하는 경우 있습니다. 투명한 활동이 사용 가능한 디스플레이 공간을 채우면 자동으로 활동을 사용하도록 구성된 경우 시스템에 둥근 모서리를 적용합니다. 기기 제조업체에서 변경합니다. 그러나 투명한 활동 (예: 사용 가능한 공간이 채워지지 않으면 사용자가 직접 결정하는 것입니다. 적용할지 여부를 결정합니다.

권한 대화상자가 사용 가능한 디스플레이 공간을 채우지 않습니다. 대화상자가 레이아웃은 일반적으로 LayoutParams.WRAP_CONTENT 대신 LayoutParams.MATCH_PARENT

표시되는 시작 활동 위에 둥근 모서리가 있는 대화상자가 올바르게 배치되었습니다.

호환성 해결 방법

대화상자 활동을 실행하는 활동은 사용자가 응답했습니다

시스템은 투명한 활동이 첫 번째 불투명 활동이 액티비티 스택의 투명한 활동 아래에 있고 다음과 관련된 제약 조건을 포함합니다.

크기 호환성 모드
방향
가로세로 비율

Unity 게임

Unity 게임은 Android 전체 화면 또는 멀티 윈도우 모드에서 실행됩니다. 하지만 많은 Unity 게임이 앱이 배치되면 포커스를 잃고 콘텐츠 그리기를 중지함 멀티 윈도우 모드를 지원합니다.

문제

Unity에서 Resizable Window을 추가했습니다. 옵션이 추가되었습니다. 하지만 초기 구현이 액티비티 수명 주기에 반응하지 않고 멀티 윈도우 모드가 올바르게 작동하지 않아 앱에 포커스가 없을 때 재생을 정지하는 UnityPlayer 플레이어는 검은색 화면이나 게임의 마지막 정지된 프레임이 표시될 수 있습니다. 게임플레이가 다음 경우에만 재개됨 사용자가 화면을 탭했습니다. Unity 엔진을 사용하는 많은 앱에서 이 문제에 직면하며 멀티 윈도우 모드에서 검은색 창으로 렌더링할 수 있습니다.

게임이 멀티 윈도우 모드에서 포커스를 잃고 검은색 창으로 렌더링됩니다.

최적화

Unity를 2019.4.40 이상으로 업그레이드하고 게임을 다시 내보내세요. 이 옵션에서 Resizable Window 옵션 선택됨 Android 플레이어 설정(그렇지 않은 경우) 게임이 안에서 완전히 보이는데도 포커스가 없으면 게임이 일시중지됩니다. 멀티 윈도우 모드를 지원합니다.

포커스가 없는 경우에도 게임이 멀티 윈도우 모드에서 콘텐츠를 올바르게 렌더링합니다.

호환성 해결 방법

기기 제조업체는 OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS 앱에 가짜 포커스 이벤트를 제공하기 위해 멀티 윈도우 모드를 지원합니다. 재정의를 사용하면 활동이 콘텐츠를 다시 그리고 블랙아웃되지 않아야 합니다.

앱의 호환성 문제 테스트

앱을 테스트하고 다양한 폼 팩터에서 어떻게 작동하는지 이해하려면 다음 리소스를 활용하세요.

기기 스트리밍: 프로덕션 기기( 참조 기기)에 사용하는 경우에는 Firebase 기반 Android 기기 스트리밍
Android 스튜디오 Hedgehog의 에뮬레이터: 에뮬레이터에 대한 자세한 내용은 다음을 확인하세요. 가상 기기 만들기 및 관리하기
Android 스튜디오 크기 조절 가능한 에뮬레이터: 가상 머신에 액세스하는 방법에 관한 정보 자세한 내용은 Android Emulator에서 앱 실행을 참고하세요.

레터박스 처리됨

각 활동이 앱에서 사용 가능한 모든 디스플레이 공간을 사용할 수 있는지 확인합니다. 먼저 테스트 폴더에서 다음 코드를 선언합니다.

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()
    }
}

자바

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();
}

그런 다음 테스트를 실행하여 동작을 어설션하고 타겟 활동이 레터박스 형식:

Kotlin

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

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

자바

@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();
        });
    }
}

이런 종류의 테스트는 테스트를 통과하고 앱의 앱에서 사용할 수 있는 전체 디스플레이 공간을 차지합니다. 앱 테스트 를 사용하여 일관된 동작을 보장합니다.

앱별 재정의

Android는 앱의 구성된 동작을 변경하는 재정의를 제공합니다. 대상 예를 들어 FORCE_RESIZE_APP 재정의는 크기 호환성 모드를 우회하고 디스플레이에 맞게 앱 크기를 조절하는 시스템 측정기준(resizeableActivity="false")이 선언됩니다.

기기 제조업체는 특정 앱이나 모든 앱에 재정의를 적용합니다. 특정 대형 화면 기기에서 작동합니다. Android 14 (API 수준 34) 이상에서 사용자는 기기 설정을 통해 앱에 재정의를 적용할 수 있습니다.

사용자별 앱 재정의

Android 14 이상에서는 설정 메뉴를 통해 사용자가 관점을 변경할 수 있습니다. 앱 비율 대형 화면 기기(예: 기기에서 메뉴를 구현합니다.

메뉴에는 기기에 설치된 모든 앱의 목록이 포함됩니다. 사용자는 그런 다음 앱의 가로세로 비율을 3:4, 1:1, 전체 화면 또는 기타 값으로 설정합니다. 기기 제조업체에서 구성한 것입니다 사용자는 가로세로 비율을 다음과 같이 재설정할 수도 있습니다. 앱 매니페스트에 지정된 앱 기본값입니다.

앱은 다음 PackageManager.Property 태그를 설정하여 호환성 재정의를 선택 해제할 수 있습니다.

PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE

사용자 가로세로 비율 호환성 재정의를 선택 해제하려면 속성을 추가합니다. 앱 매니페스트에 추가하고 값을 false로 설정합니다.
```
<application>
    <property
        android:name="android.window.
        PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE"
        android:value="false" />
</application>
```
앱이 기기 설정의 앱 목록에서 제외됩니다. 사용자 수 앱의 가로세로 비율을 재정의할 수 없습니다.

속성을 true로 설정해도 효과가 없습니다.
PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE

사용자 가로세로 비율 호환성의 전체 화면 옵션 선택 해제 앱 매니페스트에 속성을 추가하고 값을 false:
```
<application>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE"
        android:value="false" />
</application>
```
전체 화면 옵션은 기기 설정 사용자는 전체 화면 재정의를 적용할 수 없습니다. 있습니다.

주의: PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE false인 경우 이 속성은 아무런 영향을 미치지 않습니다.

이 속성을 true로 설정해도 효과가 없습니다.

모든 화면에 맞게 앱 최적화: 가로세로 비율 제한을 설정하지 마세요. 있습니다. 창 크기 클래스를 사용하여 다양한 크기 지원 레이아웃을 지정합니다.

기기 제조업체 앱별 재정의

기기 제조업체는 일부 기기에 앱별로 재정의를 적용합니다. 참조 기기는 일부 재정의를 실행할 수 있습니다.

앱에서는 대부분의 재정의를 선택 해제할 수 있습니다. 자세한 내용은 앱별 재정의 표).

호환성을 사용하여 재정의를 사용 설정하거나 사용 중지한 상태로 앱을 테스트할 수 있습니다. 프레임워크 (호환성 프레임워크 도구 참고) 사용 설정하면 재정의가 전체 앱에 적용됩니다.

또한 Android 디버그 브리지 (adb)를 사용하여 재정의를 사용 중지하고 앱에 적용할 재정의를 결정합니다.

다음과 같이 재정의를 사용 설정 또는 중지합니다.

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

참조 기기의 경우 어떤 재정의가 적용되는지 확인합니다. 앱:

adb shell dumpsys platform_compat | grep <package name>

다음 표에는 사용 가능한 재정의와 앱이 재정의에 의존하지 않아도 되도록 앱을 최적화하세요. 추가할 수 있는 항목: 속성 플래그를 앱 매니페스트에 추가하여 일부 재정의를 선택 해제하세요.

앱별 재정의
유형	이름	ID	설명
크기 조정 가능 여부	FORCE_RESIZE_APP	174042936	구성 변경 시 앱의 크기 호환성 모드를 우회합니다.
	FORCE_NON_RESIZE_APP	181136395	구성 변경 시 앱이 크기 호환성 모드로 강제 전환됩니다.
가로세로 비율	OVERRIDE_MIN_ASPECT_RATIO	174042980	다른 가로세로 비율 재정의를 적용하려면 게이트키퍼 재정의를 사용 설정해야 합니다.
	OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY	203647190	사용 설정하면(기본값) 재정의 범위가 세로 모드 전용 활동으로 제한됩니다.
	OVERRIDE_MIN_ASPECT_RATIO_MEDIUM	180326845	최소 가로세로 비율을 3:2로 변경합니다.
	OVERRIDE_MIN_ASPECT_RATIO_LARGE	180326787	최소 가로세로 비율을 16:9로 변경합니다.
	OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN	208648326	디스플레이 크기의 50%(또는 화면 분할 가로세로 비율)에 맞게 최소 가로세로 비율을 변경합니다.
	OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN	218959984	기기가 세로 모드일 때 앱이 전체 화면으로 표시되도록 최소 가로세로 비율 재정의를 사용 중지합니다.
방향	OVERRIDE_ANY_ORIENTATION	265464455	모든 방향 재정의를 사용 설정합니다.
	<ph type="x-smartling-placeholder"></ph> OVERRIDE_ANY_ORIENTATION_TO_USER	310816437	방향, 크기 조절 가능 여부, 가로세로 비율 제한을 재정의합니다.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT	265452344	활동에 방향이 정의되지 않은 경우 방향이 세로 모드가 되도록 재정의합니다.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	활동에 방향이 정의되지 않은 경우 방향이 `nosensor`(기기의 자연스러운 방향 사용)가 되도록 재정의합니다.
	OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE	266124927	가로 모드 전용 앱을 180도 회전합니다.
	OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA	265456536	방향 재정의 범위를 앱이 카메라에 연결될 때로 제한합니다.
	OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION	255940284	작업이 전체 화면일 때(레터박스일 때도 포함) 고정된 가로 모드의 자연스러운 방향으로 디스플레이를 설정합니다.
	OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION	254631730	무한 회전을 방지하기 위해 앱의 방향 요청을 무시합니다.
	OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED	273509367	활동이 다시 실행되는 동안 반복되는 방향 요청을 무시합니다. Android는 앱이 1초 이내에 새로운 방향을 두 번 이상 요청한다고 감지하면 이를 순환 무한 루프로 간주하고 재정의를 적용합니다.
	OVERRIDE_RESPECT_REQUESTED_ORIENTATION	236283604	기기 제조업체에서 방향 요청 무시 설정을 사용 중지하여 레터박스를 방지합니다.
Sandbox API	NEVER_SANDBOX_DISPLAY_APIS	184838306	디스플레이 API의 동작을 변경하지 못하게 합니다.
	ALWAYS_SANDBOX_DISPLAY_APIS	185004937	앱의 `Display` API가 앱 경계를 반환하도록 강제합니다. `Display` API는 논리적 디스플레이 영역 경계를 반환하지만 앱에서는 `Display` API가 앱 경계를 반환한다고 가정하여 UI 문제가 발생하는 경우도 있습니다.
	OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS	237531167	앱에서 사용되는 `View` API가 앱 경계를 반환하도록 강제합니다. `View` API는 논리적 디스플레이 영역 경계를 반환하지만 앱에서는 `View` API가 앱 경계를 반환한다고 가정하여 UI 문제가 발생하는 경우도 있습니다.
카메라 호환성	OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION	263959004	강제 회전을 사용 중지합니다. 기본적으로 모든 고정 방향 카메라 앱은 카메라 미리보기가 열릴 때 강제로 회전됩니다.
	OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH	264304459	카메라 미리보기가 강제 회전될 때 적용되는 기본 하드 새로고침을 삭제합니다.
	OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE	264301586	카메라 미리보기가 강제로 회전될 때 하드 새로고침을 소프트 새로고침으로 전환합니다. 이렇게 하면 강제로 회전하는 동안 상태가 유지될 수 있습니다. 기본적으로 Android는 카메라 미리보기가 강제로 회전될 때 하드 새로고침을 적용합니다. 하드 새로고침은 앱이 이전 상태를 캐시한 방식에 따라 앱 상태가 손실되거나 블랙아웃되는 문제가 발생할 수 있습니다.
	OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT	250678880	내부 전면 카메라의 이미지 버퍼를 자릅니다. 재정의를 사용 중지하면 내부 전면 카메라 자르기가 삭제되고 카메라 미리보기의 시야가 증가합니다. 기본적으로 일부 폴더블 (참조 기기 참고)에서는 시스템이 내부 전면 카메라를 사용할 때 모든 카메라 앱의 카메라 미리보기를 자릅니다.
기타	OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS	263259275	앱이 화면 분할 모드에서 포커스를 잃을 때 블랙아웃되는 것을 방지합니다. 앱은 앱 콘텐츠를 그리기 전에 포커스를 기다리며 이로 인해 앱이 정지되거나 블랙아웃될 수 있습니다. 재정의를 사용하면 Android에서 앱에 가짜 포커스 이벤트를 전송하고 이는 앱에 콘텐츠 그리기를 다시 시작하도록 알립니다.

FORCE_RESIZE_APP

재정의가 적용되는 패키지의 크기를 조절할 수 있도록 강제합니다. 사용 안 함 앱을 멀티 윈도우 모드로 전환할 수 있는지 여부를 변경하지만 앱이 화면 크기가 조절될 때 크기 호환성 모드로 전환하지 않고 크기를 조절할 수 있습니다.

앱이 재정의와 동일한 결과를 달성하는 방법

앱 매니페스트에서 android:resizeableActivity 속성을 true 또는 멀티 윈도우 모드를 사용 중지하는 동안 크기 조절 지원 android:resizeableActivity=false, android.supports_size_changes 설정 metadata 플래그를 true로 설정합니다.

앱 최적화 방법

반응형/적응형 레이아웃을 사용하면 앱이 모든 디스플레이 크기에 맞게 조정되고 가로세로 비율 자세한 내용은 다양한 화면 크기를 지원합니다.

재정의 사용 중지 또는 선택 해제 방법

속성 플래그 PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES를 다음으로 설정합니다. false입니다.

재정의를 조정하는 속성 플래그

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

재정의를 테스트하는 adb 명령어

재정의를 적용하고 앱의 크기를 조절할 수 있도록 하려면 다음을 실행합니다.

adb shell am compat enable FORCE_RESIZE_APP <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable FORCE_RESIZE_APP <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

FORCE_NON_RESIZE_APP

재정의가 적용되는 패키지의 크기를 조절할 수 없도록 강제합니다. 크기 호환성 모드로 전환해야 합니다.

앱이 재정의와 동일한 결과를 달성하는 방법

android:resizeableActivity 속성과 앱 매니페스트에서 android.supports_size_changes 메타데이터 플래그를 false로 설정합니다. 방향 또는 가로세로 비율 제한을 선언합니다.

앱 최적화 방법

크기를 조절해도 제대로 작동하는 모든 앱은 android:resizeableActivity 또는 android.supports_size_changes를 true로 설정 다른 앱은 크기가 조절될 때 잘 작동하도록 개선되어야 합니다. 자세한 내용은 android:resizeableActivity를 전송합니다.

재정의 사용 중지 또는 선택 해제 방법

속성 플래그 PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES를 다음으로 설정합니다. false입니다.

재정의를 조정하는 속성 플래그

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

재정의를 테스트하는 adb 명령어

재정의를 적용하고 앱의 크기를 조절할 수 없도록 하려면 다음을 실행합니다.

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable FORCE_NON_RESIZE_APP <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

OVERRIDE_MIN_ASPECT_RATIO

지정된 최소 가로세로 비율을 강제하는 모든 재정의의 게이트키퍼입니다.

앱이 재정의와 동일한 결과를 달성하는 방법

활동 또는 앱 수준에서 android:minAspectRatio를 설정합니다.

앱 최적화 방법

앱에서 가로세로 비율 제한을 설정하지 마세요. 앱이 다양한 화면 크기에 대해 자세히 알아보세요. 창 크기 클래스 사용 은 앱이 차지하는 공간의 크기에 따라 다양한 레이아웃을 지원할 수 있습니다. 화면 Compose WindowSizeClass API를 참고하세요. 및 View WindowSizeClass API.

재정의 사용 중지 또는 선택 해제 방법

가로세로 비율 제한 지정 또는 속성 플래그 설정 PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE에서 false(으)로

재정의를 조정하는 속성 플래그

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE"
  android:value="false"/>

재정의를 테스트하는 adb 명령어

재정의를 적용하려면 다음을 실행합니다.

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

활동에 지정된 최소 가로세로 비율을 강제하는 앱 설정을 제한합니다. 사용할 수 있습니다. 기본적으로 사용 설정되어 있으며 적용됩니다. OVERRIDE_MIN_ASPECT_RATIO도 사용 설정된 경우

재정의를 테스트하는 adb 명령어

재정의를 적용하려면 다음을 실행합니다.

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

활동의 최소 가로세로 비율을 중간 값(3:2)으로 설정합니다.

앱이 재정의와 동일한 결과를 달성하는 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

앱 최적화 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의 사용 중지 또는 선택 해제 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 조정하는 속성 플래그

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 테스트하는 adb 명령어

재정의를 적용하려면 다음을 실행합니다.

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

OVERRIDE_MIN_ASPECT_RATIO_LARGE

활동의 최소 가로세로 비율을 큰 값(16:9)으로 설정합니다.

앱이 재정의와 동일한 결과를 달성하는 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

앱 최적화 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의 사용 중지 또는 선택 해제 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 조정하는 속성 플래그

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 테스트하는 adb 명령어

재정의를 적용하려면 다음을 실행합니다.

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN

화면 분할 가로세로 비율을 사용 설정합니다. 앱에서 화면 분할 모드에서 사용 가능한 공간을 확보하여 레터박스를 방지합니다.

앱이 재정의와 동일한 결과를 달성하는 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

앱 최적화 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의 사용 중지 또는 선택 해제 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 조정하는 속성 플래그

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 테스트하는 adb 명령어

재정의를 적용하려면 다음을 실행합니다.

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN

세로 모드 전체 화면에서 최소 가로세로 비율 재정의를 사용 중지하여 모두 사용합니다. 사용할 수 있습니다.

앱이 재정의와 동일한 결과를 달성하는 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

앱 최적화 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의 사용 중지 또는 선택 해제 방법

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 조정하는 속성 플래그

OVERRIDE_MIN_ASPECT_RATIO를 참고하세요.

재정의를 테스트하는 adb 명령어

재정의를 적용하려면 다음을 실행합니다.

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

OVERRIDE_ANY_ORIENTATION

다음 재정의를 사용 설정하여 모든 방향을 재정의합니다.

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

앱이 재정의와 동일한 결과를 달성하는 방법

activity:screenOrientation 매니페스트 속성을 설정합니다. 또는 Activity#setRequestedOrientation() API를 사용하세요.

앱 최적화 방법

앱은 모든 방향을 지원해야 합니다. 방향 변경은 두 가지 방법 중 하나로 처리할 수 있습니다. 시스템 소멸 및 앱 재생성 또는 구성 변경사항 관리 확인할 수 있습니다 구성 변경을 직접 관리하는 경우 앱 상태는 ViewModel를 사용하여 보관됨 극히 드문 경우지만, 방향은 작은 디스플레이에서만 사용할 수 있으며, 그렇게 하면 사용자가 필요에 따라 앱을 회전할 수 있습니다. Android 12L 및 이후 버전에서는 고정된 방향은 기기 설정에 의해 재정의될 수 있습니다. 자세히 알아보기 구성 변경 처리 및 구성 변경 지원에 관한 정보 구성 변경 처리를 참고하세요. ViewModel 개요, 앱 방향이 제한됨 휴대전화에서만 사용할 수 있습니다.

재정의 사용 중지 또는 선택 해제 방법

속성 플래그 설정 PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE false에게.

재정의를 조정하는 속성 플래그

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"
  android:value="true|false"/>

재정의를 테스트하는 adb 명령어

재정의를 적용하려면 다음을 실행합니다.

adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>

재정의를 삭제하려면 다음을 실행합니다.

adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>

참고: 명령어는 일시적으로 재정의를 적용하거나 삭제합니다.

사용자에_한_어떤_또는_모두_재정의

앱이 사용 가능한 디스플레이 공간을 채우도록 합니다. 모든 방향 재정의 크기 조절 가능 여부, 가로세로 비율 제한 또한 모든 호출을 무시함 Activity#setRequestedOrientation()

앱이 재정의와 동일한 결과를 달성하는 방법

android:screenOrientation 매니페스트를 설정하지 마세요. 속성을 사용하거나 속성을 "user"로 설정하세요.
android:resizeableActivity 매니페스트 설정 속성을 true로 설정합니다.

참고: android:minAspectRatio 및 다음과 같은 경우 android:maxAspectRatio가 무시됩니다. resizeableActivity을 true(으)로 설정했습니다.
작은 화면에서 멀티 윈도우를 사용 중지하면서 앱 크기 조절 지원 사용하려면 android:resizeableActivity=false android.supports_size_changes 메타데이터 플래그를 true로 설정합니다. 설정하지 마세요. minAspectRatio 및 maxAspectRatio.

참고: Android 12 (API 수준 31)에서는 모든 앱이 멀티 윈도우 모드로 실행됩니다. 앱 구성과 관계없이 대형 화면 (sw >= 600dp) 자세한 내용은 멀티 윈도우 지원.

앱 최적화 방법

앱이 모든 방향을 지원하도록 사용 설정합니다. screenOrientation를 설정하지 않음 앱 매니페스트에 해당 사양을 명시해야 합니다. 앱 크기 조절 가능 여부 지원 가로 세로 비율을 모두 표시하려면 android:resizeableActivity 속성을 true로 설정하세요. 자세한 내용은 다양한 화면 크기를 지원합니다.

기기 호환성 모드

참조 기기

일반적인 호환성 문제

레터박스

문제

세로 모드 방향으로 제한된 앱은 가로 모드 기기에서 사용할 수 없습니다.

최적화

앱이 모든 기기 방향을 지원합니다.

호환성 해결 방법

크기 호환성 모드

문제

크기를 조절할 수 없는 앱이 멀티 윈도우 모드에서 비정상 종료됩니다.

최적화

앱이 모든 창 크기에서 작동합니다.

호환성 해결 방법

가로 모드 방향으로 레터박스 처리된 세로 모드 전용 앱이 다시 시작 컨트롤로 재조정됩니다.

깜박이는 루프

문제

세로 모드 디스플레이의 가로 모드 전용 앱은 Activity#setRequestedOrientation()을 반복적으로 호출합니다.

최적화

앱이 구성 변경을 처리하고 방향을 제한하지 않으므로 깜박이는 루프에 들어가지 않습니다.

호환성 해결 방법

카메라 미리보기

문제

대형 화면 폴더블에서 카메라 미리보기가 잘못 정렬되고 왜곡됩니다.

최적화

카메라 미리보기가 모든 기기 방향에서 올바르게 정렬되고 조정됩니다.

호환성 해결 방법

태블릿: 세로 모드 제한 앱을 강제로 회전합니다.

폴더블: 세로 모드 제한 앱을 강제로 회전합니다. 앱은 레터박스 처리되어 있습니다.

일반적으로 오용되는 API

문제

지원 중단된 API가 앱 경계를 잘못 계산합니다. 앱 콘텐츠가 화면에서 사라집니다.

최적화

API에서 앱 창 측정항목을 올바르게 계산합니다.

호환성 해결 방법

투명한 활동

문제

활동이 트램펄린에서 시작되었기 때문에 대화상자가 잘못 배치되었습니다.

최적화

둥근 모서리

표시되는 시작 활동 위에 둥근 모서리가 있는 대화상자가 올바르게 배치되었습니다.

호환성 해결 방법

Unity 게임

문제

게임이 멀티 윈도우 모드에서 포커스를 잃고 검은색 창으로 렌더링됩니다.

최적화

포커스가 없는 경우에도 게임이 멀티 윈도우 모드에서 콘텐츠를 올바르게 렌더링합니다.

호환성 해결 방법

앱의 호환성 문제 테스트

레터박스 처리됨

Kotlin

자바

Kotlin

자바

앱별 재정의

사용자별 앱 재정의

기기 제조업체 앱별 재정의

FORCE_RESIZE_APP

앱이 재정의와 동일한 결과를 달성하는 방법

앱 최적화 방법

재정의 사용 중지 또는 선택 해제 방법

재정의를 조정하는 속성 플래그

재정의를 테스트하는 adb 명령어

FORCE_NON_RESIZE_APP

앱이 재정의와 동일한 결과를 달성하는 방법

앱 최적화 방법

재정의 사용 중지 또는 선택 해제 방법

재정의를 조정하는 속성 플래그

재정의를 테스트하는 adb 명령어

OVERRIDE_MIN_ASPECT_RATIO

앱이 재정의와 동일한 결과를 달성하는 방법

앱 최적화 방법

재정의 사용 중지 또는 선택 해제 방법

재정의를 조정하는 속성 플래그

재정의를 테스트하는 adb 명령어

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

앱이 재정의와 동일한 결과를 달성하는 방법

앱 최적화 방법

재정의 사용 중지 또는 선택 해제 방법

세로 모드 디스플레이의 가로 모드 전용 앱은 `Activity#setRequestedOrientation()`을 반복적으로 호출합니다.