生成されたウィジェット プレビューを使用すると、ウィジェットの動的でパーソナライズされたプレビューを作成して、ユーザーのホーム画面にどのように表示されるかを正確に反映できます。これらはプッシュ API を介して提供されます。つまり、アプリは、ウィジェット ホストから明示的なリクエストを受け取ることなく、ライフサイクルの任意の時点でプレビューを提供します。
このガイドでは、Glance ベースのウィジェットのプレビューを提供する方法について説明します。RemoteViews を使用してウィジェットを実装している場合は、ウィジェット選択ツールにプレビューを追加するをご覧ください。
Glance ウィジェットのアプリのウィジェット選択ツールのエクスペリエンスを改善するには、Android 15 以降のデバイスで GlanceAppWidget.providePreview を使用して生成されたウィジェット プレビューを提供し、下位バージョンでは previewImage を指定します。また、生成されたプレビューが利用できない場合は、Android 15 以降のフォールバックとして指定します。
詳しくは、YouTube の ライブ情報とウィジェットでアプリを充実させるをご覧ください。
生成されたウィジェットのプレビュー用にアプリをセットアップする
Android 15 以降のデバイスで生成されたウィジェット プレビューを表示するには、まずモジュールの build.gradle ファイルで compileSdk の値を 35 以上に設定して、ウィジェット選択ツールで生成されたプレビューを有効にします。
アプリは 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 つのサイズを指定します。以前の Android バージョンをサポートするには、少なくとも 1 つの previewImage を指定します。さまざまなグリッドサイズに適した最小 DP 値については、ウィジェット設計ガイダンスをご覧ください。
古い Android バージョンをサポートする
Android 14 以前を搭載したデバイスでウィジェットのプレビューを表示する場合、または Android 15 以降で生成されたプレビューを使用できない場合は、previewImage 属性を指定します。
ウィジェットの外観を変更する場合は、プレビュー画像を更新します。