간단한 위젯 만들기

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 우선 AppWidgetProvider 클래스를 사용하여 브로드캐스트 처리 섹션을 참고하세요.

위젯 레이아웃 만들기

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

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

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

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

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

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

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

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

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)과 이전 Android 11 이하를 타겟팅하는 레이아웃(기본 res/layout 폴더)입니다.

둥근 모서리 구현

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

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