이 페이지에는 Android 12 (API 수준 31)부터 사용할 수 있는 선택적 위젯 개선사항에 관한 세부정보가 포함되어 있습니다. 이러한 기능은 선택사항이지만 사용자의 위젯 환경을 구현하고 개선하는 것은 간단합니다.
동적 색상 사용
Android 12부터 위젯은 버튼, 배경, 기타 구성요소에 기기 테마 색상을 사용할 수 있습니다. 이를 통해 여러 위젯 간에 전환이 원활해지고 일관성이 유지될 수 있습니다.
동적 색상을 구현하는 방법에는 두 가지가 있습니다.
루트 레이아웃에서 시스템의 기본 테마(
@android:style/Theme.DeviceDefault.DayNight
)를 사용합니다.Android용 Material 구성요소 v1.6.0부터 사용할 수 있는 Android용 Material 구성요소 라이브러리의 Material 3 테마 (
Theme.Material3.DynamicColors.DayNight
)를 사용합니다.
테마가 루트 레이아웃에 설정되면 루트 또는 그 하위 요소의 공통 색상 속성을 사용하여 동적 색상을 선택할 수 있습니다.
사용할 수 있는 색상 속성의 예는 다음과 같습니다.
?attr/primary
?attr/primaryContainer
?attr/onPrimary
?attr/onPrimaryContainer
Material 3 테마를 사용하는 다음 예에서 기기의 테마 색상은 '보라색'입니다. 강조 색상과 위젯 배경은 그림 1과 2와 같이 밝은 모드와 어두운 모드에 맞게 조정됩니다.
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:background="?attr/colorPrimaryContainer"
android:theme="@style/Theme.Material3.DynamicColors.DayNight">
<ImageView
...
app:tint="?attr/colorPrimaryContainer"
android:src="@drawable/ic_partly_cloudy" />
<!-- Other widget content. -->
</LinearLayout>
동적 색상의 하위 호환성
동적 색상은 Android 12 이상을 실행하는 기기에서만 사용할 수 있습니다. 이전 버전에 맞춤 테마를 제공하려면 기본 테마 속성을 사용하여 사용자 지정 색상과 새 한정자 (values-v31
)가 있는 기본 테마를 만듭니다.
다음은 Material 3 테마를 사용하는 예입니다.
<resources>
<style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
<!-- Override default colorBackground attribute with custom color. -->
<item name="android:colorBackground">@color/my_background_color</item>
<!-- Add other colors/attributes. -->
</style>
</resources>
<resources>
<!-- Do not override any color attribute. -->
<style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>
<resources>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
...
android:background="?android:attr/colorBackground"
android:theme="@style/MyWidgetTheme" />
</resources>
음성 지원 사용 설정
앱 작업을 사용하면 Google 어시스턴트가 관련 사용자 음성 명령에 응답하여 위젯을 표시할 수 있습니다. 기본 제공 인텐트 (BIIs)에 응답하도록 위젯을 구성하면 앱에서 Android 및 Android Auto와 같은 어시스턴트 표시 경로에 위젯을 사전에 표시할 수 있습니다. 사용자는 어시스턴트가 표시한 위젯을 런처에 고정하여 향후 참여를 유도할 수 있습니다.
예를 들어 운동 앱의 운동 요약 위젯을 구성하여 GET_EXERCISE_OBSERVATION
BII를 트리거하는 사용자 음성 명령을 처리할 수 있습니다. 사용자가 "Hey Google, 내가 ExampleApp에서 이번주에 몇 km나 뛰었지?"와 같은 요청을 통해 이 BII를 트리거하면 어시스턴트는 위젯을 사전에 표시합니다.
사용자 상호작용의 여러 카테고리를 다루는 수십 개의 BII가 있으므로 거의 모든 Android 앱에서 음성용 위젯을 개선할 수 있습니다. 시작하려면 앱 작업과 Android 위젯 통합을 참고하세요.
앱의 위젯 선택 도구 환경 개선
Android 12에서는 크기 조절된 위젯 미리보기와 위젯 설명을 추가할 수 있습니다. Android 15에서는 생성된 위젯 미리보기로 앱의 위젯 선택 도구 환경을 개선할 수 있습니다.
앱의 위젯 선택 도구 환경을 개선하려면 Android 15 이상 기기에는 생성된 위젯 미리보기를, Android 12~Android 14 기기에는 크기 조절된 위젯 미리보기(previewLayout
지정)를, 이전 버전에는 previewImage
를 제공합니다.
생성된 위젯 미리보기를 위젯 선택 도구에 추가
앱이 Android 15 이상 기기의 위젯 선택 도구에 RemoteViews
를 제공할 수 있으려면 모듈 build.gradle
파일에서 compileSdk
값을 35 이상으로 설정해야 합니다. 즉, 앱은 선택 도구의 콘텐츠를 업데이트하여 사용자가 보는 콘텐츠를 더 잘 나타낼 수 있습니다.
앱은 AppWidgetManager
, setWidgetPreview
, getWidgetPreview
메서드를 사용하여 최신 맞춤 정보로 위젯의 모양을 업데이트할 수 있습니다.
Jetpack Glance로 업데이트된 미리보기 생성
Glance.compose
는 하나의 컴포지션을 실행하므로 컴포저블의 본문에는 정지 함수, 흐름 또는 유사한 비동기 호출이 사용되지 않습니다. 대신 상수 데이터를 사용해야 합니다.
다음 예에서는 Jetpack Glance를 사용하여 업데이트된 미리보기를 생성합니다.
setWidgetPreview
가 이 스니펫에서 메서드로 표시되려면 compileSdk
빌드 설정이 35 이상이어야 합니다.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
ExampleAppWidget().compose(
context = appContext
),
)
Jetpack Glance 없이 업데이트된 미리보기 생성
Glance 없이 RemoteViews
를 사용할 수 있습니다. 다음 예에서는 XML 위젯 레이아웃 리소스를 로드하고 미리보기로 설정합니다. setWidgetPreview
가 이 스니펫에서 메서드로 표시되려면 compileSdk 빌드 설정이 35 이상이어야 합니다.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
위젯 선택 도구에 확장 가능한 위젯 미리보기 추가
Android 12부터 위젯 선택 도구에 표시되는 위젯 미리보기는 크기를 조절할 수 있습니다. 위젯의 기본 크기로 설정된 XML 레이아웃으로 제공합니다. 이전에는 위젯 미리보기가 정적 드로어블 리소스였고 위젯이 홈 화면에 추가될 때 위젯이 표시되는 방식을 미리보기에서 부정확하게 반영하는 경우가 있었습니다.
확장 가능한 위젯 미리보기를 구현하려면 appwidget-provider
요소의 previewLayout
속성을 사용하여 XML 레이아웃을 대신 제공합니다.
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
현실적인 기본값 또는 테스트 값이 있는 실제 위젯과 동일한 레이아웃을 사용하는 것이 좋습니다. 대부분의 앱은 동일한 previewLayout
및 initialLayout
를 사용합니다. 정확한 미리보기 레이아웃을 만드는 방법에 관한 안내는 이 페이지의 다음 섹션을 참고하세요.
사용자의 기기가 previewLayout
를 지원하지 않는 경우 앱이 previewImage
를 사용하는 것으로 대체할 수 있도록 previewLayout
및 previewImage
속성을 모두 지정하는 것이 좋습니다. previewLayout
속성은 previewImage
속성보다 우선합니다.
정확한 미리보기를 빌드하기 위한 권장 방법
확장 가능한 위젯 미리보기를 구현하려면 appwidget-provider
요소의 previewLayout
속성을 사용하여 XML 레이아웃을 제공합니다.
<appwidget-provider
...
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
정확한 미리보기를 표시하려면 다음 단계를 완료하여 실제 위젯 레이아웃에 기본값을 직접 제공하면 됩니다.
TextView
요소의android:text="@string/my_widget_item_fake_1"
설정ImageView
구성요소에 기본 이미지 또는 자리표시자 이미지 또는 아이콘(예:android:src="@drawable/my_widget_icon"
)을 설정합니다.
기본값이 없으면 미리보기에 잘못된 값이나 빈 값이 표시될 수 있습니다. 이 접근 방식의 중요한 이점은 현지화된 미리보기 콘텐츠를 제공할 수 있다는 것입니다.
ListView
, GridView
또는 StackView
가 포함된 더 복잡한 미리보기에 권장되는 접근 방식에 관한 자세한 내용은 동적 항목이 포함된 정확한 미리보기 빌드를 참고하세요.
확장 가능한 위젯 미리보기와의 하위 호환성
Android 11 (API 수준 30) 이하에서 위젯 선택 도구가 위젯 미리보기를 표시하도록 하려면 previewImage
속성을 지정합니다.
위젯의 모양을 변경하면 미리보기 이미지를 업데이트합니다.
위젯에 이름 추가
위젯은 위젯 선택 도구에 표시될 때 고유한 이름을 가져야 합니다.
위젯 이름은 AndroidManifest.xml 파일의 위젯 receiver
요소의 label
속성에서 로드됩니다.
<receiver
….
android:label="Memories">
….
</receiver>
위젯 설명 추가
Android 12부터 위젯에 표시할 위젯 선택 도구 설명을 제공합니다.
<appwidget-provider>
요소의 description
속성을 사용하여 위젯 설명을 제공합니다.
<appwidget-provider
android:description="@string/my_widget_description">
</appwidget-provider>
이전 버전의 Android에서는 descriptionRes
속성을 사용할 수 있지만 위젯 선택 도구에서는 무시됩니다.
더 원활한 전환 사용 설정
Android 12부터 런처는 사용자가 위젯에서 앱을 실행할 때 더 원활한 전환을 제공합니다.
이 개선된 전환을 사용 설정하려면 @android:id/background
나 android.R.id.background
를 사용하여 배경 요소를 식별합니다.
// Top-level layout of the widget.
<LinearLayout
android:id="@android:id/background">
</LinearLayout>
앱은 이전 버전의 Android에서 중단 없이 @android:id/background
를 사용할 수 있지만 무시됩니다.
RemoteViews의 런타임 수정 사용
Android 12부터 RemoteViews
속성의 런타임 수정을 제공하는 여러 RemoteViews
메서드를 활용할 수 있습니다. 추가된 메서드의 전체 목록은 RemoteViews
API 참조를 확인하세요.
다음 코드 예는 이러한 메서드 중 일부를 사용하는 방법을 보여줍니다.
// Set the colors of a progress bar at runtime. remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList()) // Specify exact sizes for margins. remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)
// Set the colors of a progress bar at runtime. remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList()); // Specify exact sizes for margins. remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);