ほとんどの 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
メタデータでデフォルトの幅と高さを指定します。これらの値は、セルで定義されます。Android 12 以降では、targetCellWidth
とtargetCellHeight
が指定されている場合はセル、minWidth
とminHeight
のみが指定されている場合は dps で定義されます。ウィジェットのサイズ設定属性をご覧ください。ウィジェットがここで指定した dp 以上でレイアウトされるようにします。たとえば、多くのホストでは、アイコンやウィジェットをグリッド形式で配置します。この場合、デフォルトではホストは
minWidth
とminHeight
の制約を満たす最小の数のセルを使用してウィジェットを追加します。
前のセクションに記載されている要件に加えて、特定のプラットフォーム バージョンでホストに新しい責任を課す機能が導入されています。
ターゲットの Android バージョンに基づいてアプローチを決定する
Android 12
Android 12(API レベル 31)では、ウィジェット インスタンスがオプション バンドルで取得できる dp 単位のサイズ候補のリストを含む追加の List<SizeF>
がバンドルされています。提供されるサイズの数は、ホストの実装によって異なります。通常、ホストはスマートフォン用に 2 つのサイズ(縦向きと横向き)、折りたたみ式デバイス用に 4 つのサイズを提供します。
AppWidgetProvider
が RemoteViews
に提供できる異なる RemoteViews
の数には MAX_INIT_VIEW_COUNT
(16)の上限があります。AppWidgetProvider
オブジェクトは RemoteViews
オブジェクトを List<SizeF>
の各サイズにマッピングするため、MAX_INIT_VIEW_COUNT
サイズを超えるサイズを指定しないでください。
Android 12 では、dps に maxResizeWidth
属性と maxResizeHeight
属性も導入されています。これらの属性の少なくとも 1 つを使用するウィジェットは、属性で指定されたサイズを超えないようにすることをおすすめします。
参考情報
Glance
のリファレンス ドキュメントをご覧ください。