ウィジェット ホストを作成する

ほとんどの 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() を使用します。どちらのメソッドも、AppWidgetProvider に対する onAppWidgetOptionsChanged() コールバックをトリガーします。

ウィジェットをバインドする

ユーザーがウィジェットをホストに追加すると、バインディングと呼ばれるプロセスが発生します。バインディングとは、特定のアプリ ウィジェット 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 メタデータでデフォルトの幅と高さを指定します。これらの値はセル(targetCellWidthtargetCellHeight が指定されている場合は Android 12 以降)で定義されます。minWidthminHeight のみが指定されている場合は dps が定義されます。ウィジェットのサイズ属性をご覧ください。

    ウィジェットは、少なくともこの dp でレイアウトされるようにします。たとえば、多くのホストでは、アイコンやウィジェットをグリッドに配置しています。このシナリオでは、デフォルトで、ホストは minWidth 制約と minHeight 制約を満たす最小セル数を使用してウィジェットを追加します。

前のセクションで説明した要件に加えて、特定のプラットフォーム バージョンでは、ホストに新しい責任を担う機能が導入されています。

ターゲットとする Android バージョンに応じてアプローチを決定する

Android 12

Android 12(API レベル 31)では、ウィジェット インスタンスがオプション バンドルで取り得るサイズのリスト(dp 単位)を含む追加の List<SizeF> がバンドルされています。提供されるサイズの数はホストの実装によって異なります。ホストは通常、スマートフォン用に 2 つのサイズ(縦向きと横向き)を、4 つのサイズ(折りたたみ式用)を用意しています。

AppWidgetProviderRemoteViews に提供できる RemoteViews の数には MAX_INIT_VIEW_COUNT(16)の上限があります。AppWidgetProvider オブジェクトは RemoteViews オブジェクトを List<SizeF> の各サイズにマッピングするため、MAX_INIT_VIEW_COUNT を超えるサイズを指定しないでください。

Android 12 では、maxResizeWidth 属性と maxResizeHeight 属性も dps で導入されています。これらの属性の少なくとも 1 つを使用するウィジェットは、属性で指定されたサイズを超えないようにすることをおすすめします。

参考情報

  • Glance リファレンス ドキュメントをご覧ください。