위젯 호스트 빌드

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

이 페이지에서는 맞춤 API를 구현하는 데 필요한 책임을 중점적으로 다룹니다. AppWidgetHost AppWidgetHost를 구현하는 방법에 관한 구체적인 예는 다음과 같습니다. Android 홈 화면의 소스 코드를 LauncherAppWidgetHost

다음은 API 구현과 관련된 주요 클래스와 개념에 대한 개요입니다. 맞춤 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를 사용하면 호스트가 바인딩합니다. 이 프로세스를 사용하려면 앱에서 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)

자바

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() 드림 할당 취소해야 합니다.

  • 위젯을 추가할 때 구성 활동이 다음과 같아야 하는지 확인 시작됩니다. 일반적으로 호스트는 위젯의 구성을 실행해야 합니다. 활동이 존재하고 선택사항으로 표시되지 않은 경우 configuration_optional 및 reconfigurable 플래그. 자세한 내용은 구성 활동에서 위젯 업데이트 참조하세요. 이는 많은 위젯이 표시하기 전에 필요한 단계입니다.

  • 위젯은 AppWidgetProviderInfo에서 기본 너비와 높이를 지정합니다. 메타데이터로 변환할 수 있습니다. 이 값은 Android 12(targetCellWidth 및 targetCellHeight가 다음에 해당하는 경우) 지정된 경우, 또는 minWidth 및 minHeight만 지정된 경우 dps입니다. 자세한 내용은 위젯 크기 조정 속성.

    위젯이 이 dps 이상으로 배치되었는지 확인하세요. 대상 예를 들어, 많은 호스트는 아이콘과 위젯을 그리드에 정렬합니다. 이 시나리오에서 기본적으로 호스트는 새 코드를 가져오는 데 필요한 최소 개수의 셀을 사용하여 위젯을 추가합니다. minWidth 및 minHeight 제약 조건을 충족해야 합니다.

이전 섹션에 나열된 요구사항 외에도 플랫폼에 새로운 책임을 부여하는 기능이 도입됨에 따라 호스팅합니다

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

Android 12

Android 12 (API 수준 31)는 목록이 포함된 추가 List<SizeF>을 번들로 묶음 최대 크기를 dps 단위로 나타낸 것입니다. 제공되는 크기 수는 호스트 구현에 따라 다릅니다. 호스트는 일반적으로 두 가지 휴대전화 크기(세로 모드, 가로 모드)와 4가지 크기 제공 했습니다.

서로 다른 사용자 수에 MAX_INIT_VIEW_COUNT (16)의 제한이 있습니다. AppWidgetProvider가 제공할 수 있는 RemoteViews RemoteViews AppWidgetProvider 객체는 RemoteViews 객체를 List<SizeF>, MAX_INIT_VIEW_COUNT개를 초과하는 크기를 제공하면 안 됩니다.

또한 Android 12에서는 maxResizeWidth 드림 및 maxResizeHeight 속성을 dps 단위로 표현합니다. 이 중 하나 이상을 사용하는 위젯을 속성이 속성에 지정된 크기를 초과하지 않아야 합니다.

추가 리소스

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