ほとんどの 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
を返す場合、アプリは
ユーザーに権限「allow」の付与を求めるダイアログ現在のウィジェットの
[常に許可] を選べます今後のすべてのウィジェットをカバーします
以下のスニペットは、このダイアログの表示方法に関する例です。
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)では、リストを含む追加の List<SizeF>
がバンドルされます。
ウィジェット インスタンスがオプション バンドルから取得できる dps 単位の可能なサイズ。
指定するサイズの数はホストの実装によって異なります。ホストは通常
縦向きと横向きの 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
のリファレンス ドキュメントをご覧ください。