ウィジェットを強化する

Compose の方法を試す
Jetpack Compose は、Android で推奨される UI ツールキットです。Compose スタイルの API を使用してウィジェットを作成する方法を学習します。
Jetpack Glance →

このページでは、Android 12（API レベル 31）以降で利用できるオプションのウィジェット機能強化について詳しく説明します。これらの機能はオプションですが、実装が簡単で、ユーザーのウィジェット エクスペリエンスを向上させることができます。

ダイナミック カラーを使用する

Android 12 以降のウィジェットでは、ボタンや背景などのコンポーネントにデバイスのテーマカラーを使用できます。これにより、ウィジェット間の遷移がスムーズになり、一貫性が保持されます。

動的カラーを実現する方法は 2 つあります。

ルート レイアウトでテーマを設定したら、ルートまたはその子で共通のカラー属性を使用して、ダイナミック カラーを取得できます。

使用できる色属性の例を次に示します。

  • ?attr/primary
  • ?attr/primaryContainer
  • ?attr/onPrimary
  • ?attr/onPrimaryContainer

次の例では、マテリアル 3 テーマを使用しており、デバイスのテーマカラーは「紫」です。図 1 と図 2 に示すように、アクセント カラーとウィジェットの背景はライトモードとダークモードに合わせて調整されます。

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>
ライトモード テーマのウィジェット
図 1. ライトモードのウィジェット。
ダークモード テーマのウィジェット
図 2.ダークモードのウィジェット。

動的な色に関する下位互換性

ダイナミック カラーは、Android 12 以降を搭載したデバイスでのみご利用いただけます。以前のバージョンにカスタム テーマを提供するには、カスタムカラーと新しい限定子（values-v31）を使用して、デフォルトのテーマ属性でデフォルトのテーマを作成します。

マテリアル 3 テーマを使用した例を次に示します。

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

音声サポートを有効にする

App Actions を使用すると、Google アシスタントは関連するユーザーの音声コマンドに応じてウィジェットを表示できます。組み込みインテント（BII）に応答するようにウィジェットを設定すると、アプリは Android や Android Auto などのアシスタント サーフェスにウィジェットをプロアクティブに表示できます。ユーザーは、アシスタントに表示されたウィジェットをランチャーに固定して、今後のエンゲージメントを促すことができます。

たとえば、エクササイズ アプリのワークアウトの概要ウィジェットを構成して、GET_EXERCISE_OBSERVATION BII をトリガーするユーザーの音声コマンドに対応できます。ユーザーが「OK Google, 今週は ExampleApp で何マイル歩いた？」などのリクエストを行ってこの BII をトリガーすると、アシスタントはウィジェットをプロアクティブに表示します。

ユーザー操作の複数のカテゴリをカバーする BII が数十個あり、ほとんどすべての Android アプリで音声操作用のウィジェットを強化できます。開始するには、App Actions を Android ウィジェットと統合するをご覧ください。

アプリのウィジェット選択ツールのエクスペリエンスを改善する

Android 12 では、スケーリングされたウィジェットのプレビューとウィジェットの説明を追加できます。Android 15 では、生成されたウィジェットのプレビューを使用して、アプリのウィジェット選択ツールのエクスペリエンスを改善できます。

アプリのウィジェット選択ツールのエクスペリエンスを改善するには、Android 15 以降のデバイスでは生成されたウィジェットのプレビューを、Android 12 ～ Android 14 のデバイスではスケーリングされたウィジェットのプレビュー（previewLayout を指定）を、それ以前のバージョンでは previewImage を提供します。

生成されたウィジェット プレビューをウィジェット選択ツールに追加する

Android 15 以降のデバイスのウィジェット ピッカーに RemoteViews を提供できるようにするには、アプリはモジュールの build.gradle ファイルで compileSdk の値を 35 以上に設定する必要があります。つまり、アプリは、ユーザーが目にするものにより近い形でピッカーのコンテンツを更新できます。

アプリは AppWidgetManager、setWidgetPreview、getWidgetPreview メソッドを使用して、最新のパーソナライズされた情報でウィジェットの外観を更新できます。

Jetpack Glance で更新されたプレビューを生成する

Glance.compose は 1 つのコンポジションを実行するため、コンポーザブルの本体で suspend 関数、フロー、同様の非同期呼び出しは使用されません。代わりに、定数データを使用する必要があります。

次の例では、Jetpack Glance を使用して更新されたプレビューを生成します。このスニペットで setWidgetPreview をメソッドとして表示するには、compileSdk のビルド設定が 35 以上である必要があります。

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

Jetpack Glance を使用せずに更新されたプレビューを生成

Glance なしで RemoteViews を使用できます。次の例では、XML ウィジェット レイアウト リソースを読み込み、プレビューとして設定します。このスニペットで setWidgetPreview をメソッドとして表示するには、compileSdk ビルド設定が 35 以降である必要があります。

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

ウィジェット選択ツールにスケーラブルなウィジェット プレビューを追加する

Android 12 以降では、ウィジェット選択ツールに表示されるウィジェットのプレビューはスケーラブルです。これは、ウィジェットのデフォルトのサイズに設定された XML レイアウトとして提供します。以前は、ウィジェット プレビューは静的なドローアブル リソースだったため、場合によっては、ウィジェットをホーム画面に追加したときの表示がプレビューに正確に反映されないことがありました。

スケーラブルなウィジェット プレビューを実装するには、appwidget-provider 要素の previewLayout 属性を使用して、代わりに XML レイアウトを提供します。

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

現実的なデフォルト値またはテスト値を持つ実際のウィジェットと同じレイアウトを使用することをおすすめします。ほとんどのアプリは同じ previewLayout と initialLayout を使用します。正確なプレビュー レイアウトを作成するためのガイダンスについては、このページの次のセクションをご覧ください。

ユーザーのデバイスが previewLayout をサポートしていない場合にアプリが previewImage を使用するようにフォールバックできるように、previewLayout 属性と previewImage 属性の両方を指定することをおすすめします。previewLayout 属性は previewImage 属性よりも優先されます。

正確なプレビューを作成するための推奨アプローチ

スケーラブルなウィジェット プレビューを実装するには、appwidget-provider 要素の previewLayout 属性を使用して、XML レイアウトを提供します。

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
ウィジェットのプレビューを示す画像
図 3. デフォルトでは 3x3 の領域に表示されるが、XML レイアウトにより 3x1 の領域に収まるウィジェットのプレビュー。

正確なプレビューを表示するには、次の手順に沿って、デフォルト値を含む実際のウィジェット レイアウトを直接指定します。

  • TextView 要素の android:text="@string/my_widget_item_fake_1" を設定します。

  • ImageView コンポーネントのデフォルト画像やプレースホルダ画像、アイコン（android:src="@drawable/my_widget_icon" など）を設定する。

デフォルト値がないと、プレビューに正しくない値や空の値が表示されることがあります。このアプローチの重要なメリットは、ローカライズされたプレビュー コンテンツを提供できることです。

ListView、GridView、StackView を含む複雑なプレビューの推奨アプローチについては、動的アイテムを含む正確なプレビューを作成するをご覧ください。

スケーラブルなウィジェット プレビューに関する下位互換性

Android 11（API レベル 30）以前でウィジェット選択ツールを使用してウィジェットのプレビューを表示するには、previewImage 属性を指定します。

ウィジェットの外観を変更する場合は、プレビュー画像を更新します。

ウィジェットに名前を追加する

ウィジェット ピッカーに表示されるウィジェットには、一意の名前が必要です。

ウィジェットの名前は、AndroidManifest.xml ファイルのウィジェットの receiver 要素の label 属性から読み込まれます。

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

ウィジェットの説明を追加する

Android 12 以降では、ウィジェットに表示するウィジェット選択ツールの説明を指定します。

ウィジェット選択ツールにウィジェットとその説明が表示されている画像
図 4. ウィジェットとその説明を表示するウィジェット選択ツールのサンプル。

&lt;appwidget-provider&gt; 要素の description 属性を使用して、ウィジェットの説明を指定します。

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

以前のバージョンの Android では、descriptionRes 属性を使用できますが、ウィジェット選択ツールでは無視されます。

スムーズな遷移を有効にする

Android 12 以降では、ユーザーがウィジェットからアプリを起動すると、ランチャーにより遷移がスムーズに行われます。

この改善された遷移を有効にするには、@android:id/background または android.R.id.background を使用して背景要素を指定します。

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

アプリは Android の以前のバージョンで @android:id/background を使用できますが、無視されます。

RemoteViews のランタイム変更を使用する

Android 12 以降では、RemoteViews 属性のランタイム変更を可能にするいくつかの RemoteViews メソッドを利用できます。追加されたメソッドの完全なリストについては、RemoteViews API リファレンスをご覧ください。

次のコードサンプルは、これらのメソッドの使用方法をいくつか示しています。

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);