アプリ ウィジェットは、ホーム画面などの他のアプリに埋め込んで、定期的に更新を受け取ることができる小さなアプリビューです。これらのビューは、ユーザー インターフェースではウィジェットと呼ばれ、アプリ ウィジェット プロバイダ（またはウィジェット プロバイダ）を使用して公開できます。他のウィジェットを保持するアプリ コンポーネントは、アプリ ウィジェット ホスト（またはウィジェット ホスト）と呼ばれます。図 1 に、音楽ウィジェットの例を示します。
このドキュメントでは、ウィジェット プロバイダを使用してウィジェットを公開する方法について説明します。アプリ ウィジェットをホストする独自の AppWidgetHost を作成する方法については、ウィジェット ホストを作成するをご覧ください。
ウィジェットの設計方法については、アプリ ウィジェットの概要をご覧ください。
ウィジェット コンポーネント
ウィジェットを作成するには、次の基本コンポーネントが必要です。
AppWidgetProviderInfoオブジェクト- ウィジェットのレイアウト、更新の頻度、
AppWidgetProviderクラスなど、ウィジェットのメタデータを記述します。AppWidgetProviderInfoは、このドキュメントで説明されているように、XML で定義されます。 AppWidgetProviderクラス- ウィジェットとプログラムでやり取りするための基本的なメソッドを定義します。これにより、ウィジェットが更新、有効化、無効化、削除されたときにブロードキャストを受信します。このドキュメントで説明するように、マニフェストで
AppWidgetProviderを宣言してから、実装します。 - ビューのレイアウト
- ウィジェットの初期レイアウトを定義します。このドキュメントで説明されているように、レイアウトは XML で定義されます。
図 2 は、これらのコンポーネントがアプリ ウィジェットの処理フロー全体にどのように適合するかを示しています。
ウィジェットでユーザー構成が必要な場合は、アプリ ウィジェット構成アクティビティを実装します。このアクティビティを使用すると、ユーザーはウィジェットの設定（時計ウィジェットのタイムゾーンなど）を変更できます。
- Android 12（API レベル 31）以降では、デフォルトの構成を指定して、ユーザーが後でウィジェットを再構成できるようにすることができます。詳しくは、ウィジェットのデフォルト構成を使用するとユーザーが配置済みのウィジェットを再構成できるようにするをご覧ください。
- Android 11（API レベル 30）以前では、ユーザーがウィジェットをホーム画面に追加するたびに、このアクティビティが起動されます。
また、柔軟なウィジェット レイアウト、その他の機能強化、高度なウィジェット、コレクション ウィジェット、ウィジェット ホストの構築などの改善もおすすめします。
AppWidgetProviderInfo XML を宣言する
メタデータ設定（デフォルトのセルサイズ、サイズ変更の制約、更新の頻度など）の定義は、従来の View と Glance ベースのウィジェットでまったく同じです。
メタデータ XML ファイルを定義して構成する方法については、Glance ドキュメントの Compose ファーストの AppWidgetProviderInfo XML を宣言するセクションをご覧ください。
AppWidgetProvider クラスを使用してウィジェット ブロードキャストを処理する
プラットフォームのブロードキャスト レシーバ メカニズム、マニフェスト宣言フィルタ、ライフサイクル イベントループは、プラットフォームの下で統合されています。Compose ファーストの開発では、これらのブロードキャストは GlanceAppWidgetReceiver ラッパーを使用してオーケストレートされます。
マニフェストにレシーバを登録し、Hilt 互換のライフサイクル オーバーライドを実装する方法については、Glance ドキュメントの Compose ファーストの AppWidgetProvider クラスを使用してブロードキャストを処理するセクションをご覧ください。
ウィジェット レイアウトを作成する
ウィジェットの初期レイアウトを XML で定義し、プロジェクトの res/layout/ ディレクトリに保存する必要があります。詳しくは、デザイン ガイドラインをご覧ください。
レイアウトに慣れている場合は、ウィジェット レイアウトを簡単に作成できます。ただし、ウィジェットのレイアウトは RemoteViews に基づいており、すべての種類のレイアウトやビュー ウィジェットをサポートしているわけではありません。RemoteViews でサポートされているビューのカスタムビューまたはサブクラスは使用できません。
RemoteViews は ViewStub もサポートしています。これは、目に見えないゼロサイズの View であり、これを使用するとレイアウト リソースのインフレートを実行時に遅延できます。
ステートフルな動作のサポート
Android 12 では、次の既存のコンポーネントを使用してステートフルな動作のサポートが追加されています。
このウィジェットはまだステートレスであるため、アプリが状態を保存し、状態変化イベントを登録できるようにする必要があります。
次のコードサンプルは、これらのコンポーネントを実装する方法を示しています。
// Check the view. remoteView.setCompoundButtonChecked(R.id.my_checkbox, true) // Check a radio group. remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2) // Listen for check changes. The intent has an extra with the key // EXTRA_CHECKED that specifies the current checked state of the view. remoteView.setOnCheckedChangeResponse( R.id.my_checkbox, RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent) )
2 つのレイアウトを用意します。1 つは res/layout-v31 で Android 12 以降を搭載したデバイスをターゲットとし、もう 1 つはデフォルトの res/layout フォルダで Android 11 以前をターゲットとします。
角の丸みを実装する
外側の背景と内側の比例半径の計算は標準であり、共有されます。Compose ファーストの開発では、カスタムテーマ リソースとともに Kotlin で動的に設定できます。
古い Android デバイスで角丸を実装したり、動的スタイルを設定したりするには、Glance ドキュメントの Compose ファーストの角丸を実装するセクションをご覧ください。