위젯 호스트 빌드

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

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

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

  • 앱 위젯 호스트: AppWidgetHost는 UI에 위젯을 삽입하는 앱을 위한 AppWidget 서비스와의 상호작용을 제공합니다. AppWidgetHost에는 호스트의 자체 패키지 내에서 고유한 ID가 있어야 합니다. 이 ID는 호스트에서 지속적으로 사용됩니다. ID는 일반적으로 앱에서 할당하는 하드 코딩 값입니다.

  • 앱 위젯 ID: 각 위젯 인스턴스에는 바인딩 시 고유 ID가 할당됩니다. bindAppWidgetIdIfAllowed() 및 자세한 내용은 이어지는 위젯 바인딩 섹션을 참고하세요. 호스트는 고유 ID를 사용하여 allocateAppWidgetId() 가져옵니다. 이 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를 반환하는 경우 앱에서 사용자에게 권한을 부여하도록 요청하는 대화상자를 표시해야 합니다. 현재 위젯 추가에 '허용' 또는 향후 모든 위젯 추가에 '항상 허용'을 선택할 수 있습니다.

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

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

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

호스트 책임

AppWidgetProviderInfo 메타데이터를 사용하여 위젯의 다양한 구성 설정을 지정할 수 있습니다. 이러한 구성 옵션은 이어지는 섹션에서 자세히 다루며 호스트가 위젯 공급자와 연결된 AppWidgetProviderInfo 객체에서 가져올 수 있습니다.

모든 호스트에는 다음과 같은 책임이 있습니다.

  • 위젯을 추가할 때 앞에서 설명한 대로 위젯 ID를 할당합니다. 위젯이 호스트에서 삭제될 때 deleteAppWidgetId() 위젯 ID를 할당 취소합니다.

  • 위젯을 추가할 때 구성 활동을 실행해야 하는지 확인합니다. 일반적으로 호스트는 configuration_optional 및 reconfigurable 플래그를 모두 지정하여 위젯의 구성 활동이 있는 경우 이를 실행해야 하며 선택사항으로 표시되지 않습니다. 자세한 내용은 구성 활동에서 위젯 업데이트 를 참고하세요. 대부분의 위젯은 이 단계를 완료해야 표시됩니다.

  • 위젯은 AppWidgetProviderInfo 메타데이터에서 기본 너비와 높이를 지정합니다. 이러한 값은 셀에서 정의됩니다. Android 12부터 targetCellWidth 및 targetCellHeight가 지정된 경우 또는 minWidth 및 minHeight만 지정된 경우 dp에서 정의됩니다. 위젯 크기 조정 속성을 참고하세요.

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

접근방식에 관한 팁

이전 섹션에 나열된 요구사항 외에도 다음 팁을 염두에 두세요.

옵션 번들에는 위젯 인스턴스가 사용할 수 있는 dp의 가능한 크기 목록이 포함된 List<SizeF>가 포함될 수 있습니다. 제공되는 크기 수는 호스트 구현에 따라 다릅니다. 호스트는 일반적으로 휴대전화의 경우 두 가지 크기(세로 모드, 가로 모드)이고 폴더블의 경우 네 가지 크기를 제공합니다.

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

위젯이 dp에서 maxResizeWidth 및 maxResizeHeight 속성을 지정하는 경우 이러한 속성 중 하나 이상을 사용하는 위젯이 속성으로 지정된 크기를 초과하지 않는 것이 좋습니다.

추가 리소스

  • Glance 참조 문서를 참고하세요.