간단한 위젯 만들기

Compose 방식으로 사용해 보기
Jetpack Compose는 Android의 권장 UI 도구 키트입니다. Compose 스타일 API를 사용하여 위젯을 빌드하는 방법을 알아보세요.
Jetpack Glance →

앱 위젯은 홈 화면과 같은 다른 앱에 삽입하고 주기적인 업데이트를 받을 수 있는 소형 앱 뷰입니다. 이러한 뷰는 사용자 인터페이스에서 위젯 이라고 하며 앱 위젯 제공업체 (또는 위젯 제공업체)를 사용하여 게시할 수 있습니다. 다른 위젯을 포함하는 앱 구성요소를 앱 위젯 호스트 (또는 위젯 호스트)라고 합니다. 그림 1은 샘플 음악 위젯을 보여줍니다.

음악 위젯의 예
그림 1. 음악 위젯의 예

이 문서에서는 위젯 제공업체를 사용하여 위젯을 게시하는 방법을 설명합니다. 앱 위젯을 호스팅하기 위해 자체 AppWidgetHost를 만드는 방법에 관한 자세한 내용은 위젯 호스트 빌드를 참고하세요.

위젯을 디자인하는 방법에 관한 자세한 내용은 앱 위젯 개요를 참고하세요.

위젯 구성요소

위젯을 만들려면 다음과 같은 기본 구성요소가 필요합니다.

AppWidgetProviderInfo 객체
위젯의 레이아웃, 업데이트 빈도, AppWidgetProvider 클래스 등 위젯의 메타데이터를 설명합니다. AppWidgetProviderInfo는 이 문서에 설명된 대로 XML로 정의됩니다.
AppWidgetProvider 클래스
위젯과 프로그래매틱 방식으로 상호작용할 수 있는 기본적인 방법을 정의합니다. 이를 통해 위젯이 업데이트, 사용 설정, 사용 중지 또는 삭제될 때 브로드캐스트를 수신하게 됩니다. 이 문서에 설명된 대로 매니페스트에서 선언AppWidgetProvider한 후 구현합니다.
레이아웃 보기
위젯의 초기 레이아웃을 정의합니다. 레이아웃은 이 문서에 설명된 대로 XML 로 정의됩니다.

그림 2는 이러한 구성요소가 전반적인 앱 위젯 처리 흐름에 어떻게 들어맞는지 보여줍니다.

앱 위젯 처리 흐름
그림 2. 앱 위젯 처리 흐름

위젯에 사용자 구성이 필요한 경우 앱 위젯 구성 활동을 구현합니다. 이 활동을 통해 사용자는 시계 위젯의 시간대와 같은 위젯 설정을 수정할 수 있습니다.

또한 유연한 위젯 레이아웃, 기타 개선사항, 고급 위젯, 컬렉션 위젯, 위젯 호스트 빌드와 같은 개선사항을 권장합니다.

AppWidgetProviderInfo XML 선언

기본 셀 크기, 크기 조정 제약조건, 업데이트 빈도와 같은 메타데이터 설정을 정의하는 것은 기존 뷰와 Glance 기반 위젯 모두에서 완전히 동일합니다.

메타데이터 XML 파일을 정의하고 구성하는 방법을 알아보려면 Glance 문서의 Compose 우선 AppWidgetProviderInfo XML 선언 섹션을 참고하세요.

AppWidgetProvider 클래스를 사용하여 위젯 브로드캐스트 처리

플랫폼의 브로드캐스트 수신기 메커니즘, 매니페스트 선언 필터, 수명 주기 이벤트 루프는 플랫폼 아래에서 통합됩니다. Compose 우선 개발에서는 이러한 브로드캐스트가 GlanceAppWidgetReceiver 래퍼를 사용하여 오케스트레이션됩니다.

매니페스트에서 수신기를 등록하고 Hilt 호환 수명 주기 재정의를 구현하는 방법을 알아보려면 Glance 문서의 Compose 우선 Use the AppWidgetProvider 클래스를 사용하여 브로드캐스트 처리 섹션을 참고하세요.

위젯 레이아웃 만들기

위젯의 초기 레이아웃을 XML로 정의하고 프로젝트의 res/layout/ 디렉터리에 저장해야 합니다. 자세한 내용은 디자인 가이드라인을 참고하세요.

레이아웃에 익숙한 경우 간단히 위젯 레이아웃을 만들 수 있습니다. 레이아웃 하지만 위젯 레이아웃은 모든 종류의 레이아웃 또는 뷰 위젯을 지원하지는 않는 RemoteViews를 기반으로 한다는 것을 알아야 합니다. RemoteViews에서 지원하는 뷰의 맞춤 뷰 또는 하위 클래스는 사용할 수 없습니다.

RemoteViews는 런타임에 레이아웃 리소스를 느리게 확장하는 데 사용할 수 있는 보이지 않고 크기가 0인 View인 ViewStub도 지원합니다.

스테이트풀(Stateful) 동작 지원

Android 12에서는 다음 기존 구성요소를 사용하여 스테이트풀(Stateful) 동작 지원을 새로 추가합니다.

위젯은 여전히 스테이트리스(Stateless)입니다. 앱은 상태를 저장하고 상태 변경 이벤트에 등록해야 합니다.

상태 저장 동작을 보여주는 쇼핑 목록 위젯의 예
그림 3. 스테이트풀(Stateful) 동작의 예

다음 코드 예는 이러한 구성요소를 구현하는 방법을 보여줍니다.

Kotlin

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

자바

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

두 가지 레이아웃을 제공합니다. 하나는 Android 12 또는 이상을 실행하는 기기를 res/layout-v31에서 타겟팅하고 다른 하나는 기본 res/layout 폴더에서 이전 Android 11 이하를 타겟팅합니다.

둥근 모서리 구현

외부 배경과 내부 비례 반경을 계산하는 것은 표준이며 공유됩니다. Compose 우선 개발에서는 맞춤 테마 리소스와 함께 Kotlin에서 동적으로 설정할 수 있습니다.

모서리 반경을 구현하거나 이전 Android 기기의 동적 스타일을 설정하려면 Glance 문서의 Compose 우선 둥근 모서리 구현 섹션을 참고하세요.