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

위젯 호스트 빌드

대부분의 Android 지원 기기에서 사용할 수 있는 Android 홈 화면에서는 사용자가 앱 위젯 (또는 위젯)을 삽입하여 콘텐츠에 빠르게 액세스할 수 있습니다. 홈 화면 대체 앱 또는 유사한 앱을 빌드하고 있다면 AppWidgetHost를 구현하여 사용자가 위젯을 삽입하도록 허용할 수도 있습니다. 이는 대부분의 앱에서 해야 하는 작업은 아니지만 자체 호스트를 만드는 경우 호스트가 암시적으로 동의하는 계약 의무를 이해하는 것이 중요합니다.

이 페이지에서는 맞춤 AppWidgetHost 구현과 관련된 책임을 중점적으로 설명합니다. AppWidgetHost를 구현하는 방법에 관한 구체적인 예는 Android 홈 화면 LauncherAppWidgetHost의 소스 코드를 참고하세요.

다음은 맞춤 AppWidgetHost 구현과 관련된 키 클래스와 개념의 개요입니다.

앱 위젯 호스트: AppWidgetHost는 UI에 위젯을 삽입하는 앱을 위해 AppWidget 서비스와의 상호작용을 제공합니다. AppWidgetHost에는 호스트의 자체 패키지 내에서 고유한 ID가 있어야 합니다. 이 ID는 호스트를 사용하는 모든 경우에 유지됩니다. ID는 일반적으로 앱에서 할당하는 하드코딩된 값입니다.
앱 위젯 ID: 결합 시 각 위젯 인스턴스에 고유 ID가 할당됩니다. bindAppWidgetIdIfAllowed() 및 자세한 내용은 바인딩 위젯 섹션을 참고하세요. 호스트는 allocateAppWidgetId()를 사용하여 고유 ID를 가져옵니다. 이 ID는 위젯이 호스트에서 삭제될 때까지 위젯의 전체 기간 동안 유지됩니다. 위젯의 크기 및 위치와 같은 호스트별 상태는 호스팅 패키지에 의해 유지되고 앱 위젯 ID와 연결되어야 합니다.
앱 위젯 호스트 뷰: AppWidgetHostView를 위젯이 표시되어야 할 때마다 래핑되는 프레임으로 생각하세요. 위젯은 위젯이 호스트에 의해 확장될 때마다 AppWidgetHostView와 연결됩니다.
- 기본적으로 시스템은 AppWidgetHostView를 만들지만 호스트는 이를 확장하여 자체 AppWidgetHostView 서브클래스를 만들 수 있습니다.
- Android 12 (API 수준 31)부터 AppWidgetHostView에 동적으로 오버로드된 색상을 처리하기 위한 setColorResources() 및 resetColorResources() 메서드가 도입되었습니다. 호스트가 이러한 메서드에 색상을 제공합니다.
옵션 번들: AppWidgetHost는 옵션 번들을 사용하여 위젯이 표시되는 방식(예: 크기 범위 목록) 및 위젯이 잠금 화면에 있는지 또는 홈 화면에 있는지에 관한 정보를 AppWidgetProvider에 전달합니다. AppWidgetProvider는 이 정보를 사용하여 위젯이 표시되는 방식과 위치에 따라 위젯의 콘텐츠와 모양을 조정할 수 있습니다. updateAppWidgetOptions() 및 updateAppWidgetSize()를 사용하여 위젯의 번들을 수정할 수 있습니다. 두 메서드 모두 onAppWidgetOptionsChanged() 콜백을 AppWidgetProvider에 트리거합니다.

바인딩 위젯

사용자가 호스트에 위젯을 추가하면 바인딩 프로세스가 발생합니다. 바인딩은 특정 앱 위젯 ID를 특정 호스트 및 특정 AppWidgetProvider와 연결하는 것을 의미합니다.

API를 결합하면 호스트에서 결합을 위한 맞춤 UI를 제공할 수도 있습니다. 이 프로세스를 사용하려면 앱이 호스트의 매니페스트에서 BIND_APPWIDGET 권한을 선언해야 합니다.

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

하지만 이 단계는 첫 번째 단계일 뿐입니다. 런타임 시 사용자는 호스트에 위젯을 추가할 수 있도록 앱에 명시적으로 권한을 부여해야 합니다. 앱에 위젯을 추가할 수 있는 권한이 있는지 테스트하려면 bindAppWidgetIdIfAllowed() 메서드를 사용하세요. bindAppWidgetIdIfAllowed()가 false를 반환하는 경우 앱은 사용자에게 권한을 부여하도록 요청하는 대화상자를 표시해야 합니다. 현재 위젯 추가에는 '허용'하고 향후 모든 위젯 추가를 포괄하는 '항상 허용'입니다.

다음 스니펫은 대화상자를 표시하는 방법의 예를 보여줍니다.

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

호스트는 사용자가 추가하는 위젯에 구성이 필요한지 확인해야 합니다. 자세한 내용은 사용자가 앱 위젯을 구성할 수 있도록 사용 설정을 참고하세요.

호스트의 책임

AppWidgetProviderInfo 메타데이터를 사용하여 위젯의 다양한 구성 설정을 지정할 수 있습니다. 이러한 구성 옵션은 위젯 제공업체와 연결된 AppWidgetProviderInfo 객체에서 검색할 수 있습니다. 자세한 내용은 다음 섹션에서 설명합니다.

타겟팅하는 Android 버전과 관계없이 모든 호스트에는 다음과 같은 책임이 있습니다.

위젯을 추가할 때는 앞에서 설명한 대로 위젯 ID를 할당합니다. 위젯이 호스트에서 삭제되면 deleteAppWidgetId()를 호출하여 위젯 ID를 할당 해제합니다.
위젯을 추가할 때 구성 활동을 시작해야 하는지 확인합니다. 일반적으로 위젯의 구성 활동이 존재하고 configuration_optional 및 reconfigurable 플래그를 모두 지정하여 선택사항으로 표시되지 않은 경우 호스트는 이를 실행해야 합니다. 자세한 내용은 구성 활동에서 위젯 업데이트를 참고하세요. 이 단계는 많은 위젯이 표시되기 전에 필요한 단계입니다.

참고: 구성 활동이 반환되지 않거나 오류로 완료되지 않는 불규칙한 사례를 처리합니다.
위젯은 AppWidgetProviderInfo 메타데이터에서 기본 너비와 높이를 지정합니다. 이러한 값은 셀(Android 12부터 targetCellWidth 및 targetCellHeight가 지정된 경우)에 정의되고 minWidth 및 minHeight만 지정된 경우에는 dps로 정의됩니다. 위젯 크기 조정 속성을 참고하세요.

위젯이 이 이상의 dp로 배치되었는지 확인합니다. 예를 들어 대부분의 호스트는 아이콘과 위젯을 그리드에 정렬합니다. 이 시나리오에서 호스트는 기본적으로 minWidth 및 minHeight 제약 조건을 충족하는 최소 셀 수를 사용하여 위젯을 추가합니다.

이전 섹션에 나열된 요구사항 외에도 특정 플랫폼 버전에는 호스트에 새로운 책임을 부여하는 기능이 도입됩니다.

대상 Android 버전에 따라 접근 방식 결정

Android 12

Android 12 (API 수준 31)는 위젯 인스턴스가 옵션 번들에서 사용할 수 있는 dps 단위의 가능한 크기 목록이 포함된 추가 List<SizeF>를 번들로 묶습니다. 제공되는 크기의 수는 호스트 구현에 따라 다릅니다. 호스트는 일반적으로 휴대전화에 세로 모드와 가로 모드 등 두 가지 크기를 제공하고 폴더블에는 네 가지 크기를 제공합니다.

AppWidgetProvider가 RemoteViews에 제공할 수 있는 다양한 RemoteViews 수에는 MAX_INIT_VIEW_COUNT (16)로 제한됩니다. AppWidgetProvider 객체는 RemoteViews 객체를 List<SizeF>의 각 크기에 매핑하므로 크기를 MAX_INIT_VIEW_COUNT개 이상 제공하지 마세요.

Android 12에서는 dps 단위의 maxResizeWidth 및 maxResizeHeight 속성도 도입했습니다. 이러한 속성 중 하나 이상을 사용하는 위젯은 속성에 지정된 크기를 초과하지 않는 것이 좋습니다.

추가 리소스

Glance 참조 문서를 확인하세요.