生成されたウィジェット プレビューを使用すると、ウィジェットの動的でパーソナライズされたプレビューを作成できます。このプレビューは、ユーザーのホーム画面に表示されるウィジェットの様子を正確に反映します。これらはプッシュ API を介して提供されます。つまり、アプリはウィジェット ホストから明示的なリクエストを受け取ることなく、ライフサイクルの任意の時点でプレビューを提供します。
このガイドでは、Glance ベースのウィジェットのプレビューを提供する方法について説明します。ウィジェットが RemoteViews で実装されている場合は、ウィジェット ピッカーにプレビューを追加するをご覧ください。
Glance ウィジェットのアプリのウィジェット選択ツールのエクスペリエンスを改善するには、Android 15 以降のデバイスで GlanceAppWidget.providePreview を使用して生成されたウィジェットのプレビューを提供し、以前のバージョンでは previewImage を指定します。また、生成されたプレビューが利用できない場合は、Android 15 以降のフォールバックとして previewImage を指定します。
詳しくは、YouTube の Enrich your app with live updates and widgets をご覧ください。
生成されたウィジェットのプレビュー用にアプリをセットアップする
Android 15 以降のデバイスで生成されたウィジェットのプレビューを表示するには、まずモジュールの build.gradle ファイルで compileSdk の値を 35 以上に設定して、ウィジェット選択ツールに RemoteViews を提供できるようにします。
アプリは GlanceAppWidgetManager で setWidgetPreview を使用できます。不正使用を防ぎ、システムの健全性に関する懸念を軽減するため、setWidgetPreview はレート制限付きの API です。デフォルトの上限は 1 時間あたり約 2 回の通話です。
Jetpack Glance で更新されたプレビューを生成する
Jetpack Glance でビルドされたウィジェットの場合は、次の操作を行います。
GlanceAppWidget.providePreview関数をオーバーライドして、プレビュー用のコンポーズ可能なコンテンツを提供します。provideGlanceの場合と同様に、アプリのデータを読み込んでウィジェットのコンテンツ コンポーザブルに渡し、プレビューに正確なデータが表示されるようにします。provideGlanceとは異なり、これは再コンポーズやエフェクトのない単一のコンポジションです。GlanceAppWidgetManager.setWidgetPreviewsを呼び出して、プレビューを生成して公開します。
システムからプレビューを提供するコールバックはないため、アプリで setWidgetPreviews を呼び出すタイミングを決定する必要があります。更新戦略は、ウィジェットのユースケースによって異なります。
- ウィジェットに静的な情報が含まれている場合や、クイック アクションである場合は、アプリの初回起動時にプレビューを設定します。
- プレビューは、アプリにデータが入力された後（ユーザーのログイン後や初期設定後など）に設定できます。
- 選択したケイデンスでプレビューを更新する定期的なタスクを設定できます。
生成されたプレビューのトラブルシューティング
一般的な問題は、プレビューを生成した後、ウィジェットのドロップサイズに対して、プレビュー画像から画像、アイコン、その他のコンポーザブルが欠落していることです。このドロップ サイズは、指定されている場合は targetCellWidth と targetCellHeight で定義され、指定されていない場合はアプリ ウィジェット プロバイダ情報ファイルの minWidth と minHeight で定義されます。
これは、Android がデフォルトで、ウィジェットの最小サイズで表示されるコンポーザブルのみをレンダリングするためです。つまり、Android はデフォルトで previewSizeMode を SizeMode.Single に設定します。アプリ ウィジェット プロバイダ情報 XML の android:minHeight と android:minWidth を使用して、描画するコンポーザブルを決定します。
この問題を解決するには、GlanceAppWidget で previewSizeMode をオーバーライドして SizeMode.Responsive に設定し、DpSize 値のセットを指定します。これにより、プレビューのレンダリングに必要なすべてのレイアウト サイズが Android に伝えられ、すべての要素が正しく表示されます。
特定のフォーム ファクタ向けに最適化します。最小値から始めて、ウィジェットのブレークポイントに従って 1 つまたは 2 つのサイズを指定します。previewImage を 1 つ以上指定します（下位互換性のため）。グリッドサイズに応じた適切な最小 DP 値については、ウィジェットのデザイン ガイダンスをご覧ください。
ウィジェット プレビューに関する下位互換性
Android 15 より前のバージョンを搭載したデバイスのウィジェット選択ツールでウィジェットのプレビューを表示できるようにする、または Android 15 以降で生成されたプレビューのフォールバックとして、previewImage 属性を指定します。
ウィジェットの外観を変更する場合は、プレビュー画像を更新します。