このページは Cloud Translation API によって翻訳されました。

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

ほとんどの Android 搭載デバイスで利用できる Android のホーム画面では、ユーザーの埋め込みのアプリウィジェット（またはウィジェット）コンテンツにすばやくアクセスできますホーム画面の代替となるアプリやユーザーがウィジェットを埋め込めるように、 AppWidgetHost。これは違います。ほとんどのアプリで必要な作業ですが、独自のホストを作成する場合は、ホストが暗黙的に同意する契約上の義務を理解することが重要です。

このページでは、カスタムマシンタイプの実装に伴う責任を中心に AppWidgetHost。AppWidgetHost を実装する方法の具体例については、以下をご覧ください。 Android のホーム画面のソースコードを見ると、 LauncherAppWidgetHost。

ここでは、Terraform の実装に関する主なクラスとコンセプトの概要を説明します。カスタム 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 を使用すると、ホストは 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 になります。詳しくは、ウィジェットのサイズ設定属性。

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

前のセクションで説明した要件に加えて、インフラストラクチャのプラットフォームバージョンでは、新しい責任を組織内に配置するホストします。

対象とする Android バージョンに基づいてアプローチを決定する

Android 12

Android 12（API レベル 31）では、リストを含む追加の List<SizeF> がバンドルされます。ウィジェットインスタンスがオプションバンドルから取得できる dp 単位の可能なサイズ。指定するサイズの数はホストの実装によって異なります。ホストは通常縦向きと横向きの 2 種類と 4 種類のサイズを提供折りたたみ式デバイス向けのおすすめの方法です

異なる数に MAX_INIT_VIEW_COUNT（16）の上限があります AppWidgetProvider が提供できる RemoteViews RemoteViews。 AppWidgetProvider オブジェクトは、RemoteViews オブジェクトを List<SizeF>、指定できるサイズは MAX_INIT_VIEW_COUNT 個までです。

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

参考情報

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