アプリ ウィジェットは、他のアプリ(ホーム画面など)に埋め込むことができる小さなアプリビューで、定期的な更新を受信できます。これらのビューは、ユーザー インターフェースではウィジェットと呼ばれ、アプリ ウィジェット プロバイダ(またはウィジェット プロバイダ)で公開できます。他のウィジェットを保持するアプリ コンポーネントは、アプリ ウィジェット ホスト(またはウィジェット ホスト)と呼ばれます。図 1 に音楽ウィジェットの例を示します。
このドキュメントでは、ウィジェット プロバイダを使用してウィジェットを公開する方法について説明します。アプリ ウィジェットをホストするための独自の AppWidgetHost
を作成する方法については、ウィジェット ホストを作成するをご覧ください。
ウィジェットの設計方法については、アプリ ウィジェットの概要をご覧ください。
ウィジェット コンポーネント
ウィジェットを作成するには、次の基本コンポーネントが必要です。
AppWidgetProviderInfo
オブジェクト- ウィジェットのレイアウト、更新頻度、
AppWidgetProvider
クラスなど、ウィジェットのメタデータを記述します。このドキュメントで説明するように、AppWidgetProviderInfo
は XML で定義されます。 AppWidgetProvider
クラス- プログラムでウィジェットとやり取りできるようにする基本的なメソッドを定義します。これにより、ウィジェットが更新、有効化、無効化、削除されたときにブロードキャストを受信します。マニフェストで
AppWidgetProvider
を宣言してから、このドキュメントの説明に従って実装します。 - ビューのレイアウト
- ウィジェットの初期レイアウトを定義します。このドキュメントで説明するように、レイアウトは XML で定義されます。
図 2 は、アプリ ウィジェットの処理フロー全体におけるこれらのコンポーネントの位置付けを示しています。
ウィジェットにユーザー構成が必要な場合は、アプリ ウィジェット構成アクティビティを実装します。このアクティビティでは、ユーザーはウィジェットの設定(時計ウィジェットのタイムゾーンなど)を変更できます。
- Android 12(API レベル 31)以降では、デフォルト構成を指定して、ユーザーが後でウィジェットを再構成できるようにすることができます。詳しくは、ウィジェットのデフォルト構成を使用するおよび配置されたウィジェットをユーザーが再構成できるようにするをご覧ください。
- Android 11(API レベル 30)以前では、このアクティビティはユーザーがホーム画面にウィジェットを追加するたびに起動されます。
また、柔軟なウィジェット レイアウト、その他の拡張機能、高度なウィジェット、コレクション ウィジェット、ウィジェット ホストの構築といった改善もおすすめします。
AppWidgetProviderInfo XML を宣言する
AppWidgetProviderInfo
オブジェクトは、ウィジェットの基本品質を定義します。1 つの <appwidget-provider>
要素を使用して XML リソース ファイルで AppWidgetProviderInfo
オブジェクトを定義し、プロジェクトの res/xml/
フォルダに保存します。
これを次の例に示します。
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="40dp"
android:minHeight="40dp"
android:targetCellWidth="1"
android:targetCellHeight="1"
android:maxResizeWidth="250dp"
android:maxResizeHeight="120dp"
android:updatePeriodMillis="86400000"
android:description="@string/example_appwidget_description"
android:previewLayout="@layout/example_appwidget_preview"
android:initialLayout="@layout/example_loading_appwidget"
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
android:resizeMode="horizontal|vertical"
android:widgetCategory="home_screen"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>
ウィジェットのサイズ設定属性
デフォルトのホーム画面では、高さと幅が定義されたセルのグリッドに基づいて、ウィンドウ内にウィジェットが配置されます。ほとんどのホーム画面では、ウィジェットのサイズがグリッドセルの整数の倍数であること(横に 2 つのセル、縦に 3 つのセルなど)です。
ウィジェットのサイズ設定属性を使用すると、ウィジェットのデフォルト サイズを指定し、ウィジェットのサイズの下限と上限を指定できます。ここで、ウィジェットのデフォルト サイズは、ウィジェットがホーム画面に最初に追加されたときに使用されるサイズです。
次の表に、ウィジェットのサイズ設定に関する <appwidget-provider>
属性を示します。
属性と説明 | |
---|---|
targetCellWidth 、targetCellHeight (Android 12)、minWidth 、minHeight |
targetCellWidth と targetCellHeight 、minWidth と minHeight )を指定することをおすすめします。これにより、ユーザーのデバイスが targetCellWidth と targetCellHeight をサポートしていない場合でも、アプリで minWidth と minHeight を使用できます。サポートされている場合、targetCellWidth 属性と targetCellHeight 属性は minWidth 属性と minHeight 属性よりも優先されます。 |
minResizeWidth および minResizeHeight |
ウィジェットの絶対最小サイズを指定します。これらの値は、以下の値以下でウィジェットを判読できない、または使用できないサイズを指定します。これらの属性を使用すると、ユーザーはウィジェットのサイズを、デフォルトのウィジェットのサイズよりも小さくすることができます。minResizeWidth 属性が minWidth より大きい場合、または水平方向のサイズ変更が有効になっていない場合、無視されます。resizeMode をご覧ください。同様に、minResizeHeight 属性が minHeight より大きい場合、または縦方向のサイズ変更が有効になっていない場合、その属性は無視されます。 |
maxResizeWidth および maxResizeHeight |
ウィジェットの推奨最大サイズを指定します。値がグリッドセルの寸法の倍数でない場合は、最も近いセルサイズに切り上げられます。maxResizeWidth 属性が minWidth より小さい場合、または横方向のサイズ変更が有効になっていない場合、無視されます。resizeMode を参照してください。同様に、maxResizeHeight 属性が minHeight より大きい場合、または縦方向のサイズ変更が有効になっていない場合、その属性は無視されます。
Android 12 で導入されました。 |
resizeMode |
ウィジェットのサイズを変更できるルールを指定します。この属性を使用すると、ホーム画面のウィジェットを水平方向、垂直方向、または両軸でサイズ変更できます。ユーザーはウィジェットを長押ししてサイズ変更ハンドルを表示し、水平または垂直のハンドルをドラッグしてレイアウト グリッド上でサイズを変更できます。resizeMode 属性の値には、horizontal 、vertical 、none があります。ウィジェットを水平方向や垂直方向にサイズ変更可能として宣言するには、horizontal|vertical を使用します。 |
例
上の表の属性がウィジェットのサイズに与える影響を説明するため、次の仕様を想定しています。
- グリッドセルの幅は 30 dp、高さは 50 dp です。
- 次の属性が指定されています。
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="80dp"
android:minHeight="80dp"
android:targetCellWidth="2"
android:targetCellHeight="2"
android:minResizeWidth="40dp"
android:minResizeHeight="40dp"
android:maxResizeWidth="120dp"
android:maxResizeHeight="120dp"
android:resizeMode="horizontal|vertical" />
Android 12 以降:
ウィジェットのデフォルト サイズとして targetCellWidth
属性と targetCellHeight
属性を使用します。
ウィジェットのサイズは、デフォルトで 2x2 です。ウィジェットのサイズは、最小 2x1 または最大 4x3 に縮小できます。
Android 11 以前:
ウィジェットのデフォルト サイズを計算するには、minWidth
属性と minHeight
属性を使用します。
デフォルトの幅 = Math.ceil(80 / 30)
= 3
デフォルトの高さ = Math.ceil(80 / 50)
= 2
ウィジェットのサイズは、デフォルトで 3x2 です。ウィジェットは 2x1 に縮小することも、全画面表示にすることもできます。
その他のウィジェット属性
次の表に、ウィジェットのサイズ変更以外の品質に関する <appwidget-provider>
属性を示します。
属性と説明 | |
---|---|
updatePeriodMillis |
ウィジェット フレームワークが onUpdate() コールバック メソッドを呼び出して、AppWidgetProvider からの更新をリクエストする頻度を定義します。実際の更新がこの値と時間どおりに行われるとは限りません。バッテリーを節約するため、更新頻度はできるだけ低く(1 時間に 1 回程度)にすることをおすすめします。
適切な更新期間を選択する際の考慮事項の一覧については、ウィジェット コンテンツを更新するための最適化をご覧ください。 |
initialLayout |
ウィジェット レイアウトを定義するレイアウト リソースを参照します。 |
configure |
ユーザーがウィジェットを追加したときに起動するアクティビティを定義し、ウィジェットのプロパティを設定できるようにします。ユーザーがウィジェットを設定できるようにするをご覧ください。Android 12 以降では、アプリは初期構成をスキップできます。詳しくは、ウィジェットのデフォルト構成を使用するをご覧ください。 |
description |
ウィジェットに表示するウィジェット選択ツールの説明を指定します。Android 12 で導入されました。 |
previewLayout (Android 12)および previewImage (Android 11 以前) |
previewLayout をサポートしていない場合、アプリで previewImage を使用するよう、previewImage 属性と previewLayout 属性の両方を指定することをおすすめします。詳しくは、スケーラブルなウィジェット プレビューとの下位互換性をご覧ください。 |
autoAdvanceViewId |
ウィジェットのホストによって自動進行されるウィジェット サブビューのビュー ID を指定します。 |
widgetCategory |
ウィジェットをホーム画面(home_screen )、ロック画面(keyguard )、またはその両方に表示できるかどうかを宣言します。Android 5.0 以降では、home_screen のみが有効です。 |
widgetFeatures |
ウィジェットでサポートされている機能を宣言します。たとえば、ユーザーがウィジェットを追加したときにウィジェットでデフォルトの構成を使用するには、configuration_optional フラグと reconfigurable フラグの両方を指定します。これにより、ユーザーがウィジェットを追加した後に構成アクティビティを起動できなくなります。ユーザーは後でウィジェットを再構成できます。 |
AppWidgetProvider クラスを使用してウィジェット ブロードキャストを処理する
AppWidgetProvider
クラスは、ウィジェット ブロードキャストを処理し、ウィジェットのライフサイクル イベントに応答してウィジェットを更新します。以降のセクションでは、マニフェストで AppWidgetProvider
を宣言して実装する方法について説明します。
マニフェストでウィジェットを宣言する
まず、次の例に示すように、アプリの AndroidManifest.xml
ファイルで AppWidgetProvider
クラスを宣言します。
<receiver android:name="ExampleAppWidgetProvider"
android:exported="false">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
</intent-filter>
<meta-data android:name="android.appwidget.provider"
android:resource="@xml/example_appwidget_info" />
</receiver>
<receiver>
要素には android:name
属性が必要です。この属性では、ウィジェットで使用される AppWidgetProvider
を指定します。別のプロセスで AppWidgetProvider
にブロードキャストする必要がある場合を除き、コンポーネントはエクスポートしないでください(通常は該当しません)。
<intent-filter>
要素には、android:name
属性を持つ <action>
要素を含める必要があります。この属性は、AppWidgetProvider
が ACTION_APPWIDGET_UPDATE
ブロードキャストを受け入れることを指定します。明示的に宣言する必要があるブロードキャストはこれだけです。AppWidgetManager
は、他のすべてのウィジェット ブロードキャストを必要に応じて自動的に AppWidgetProvider
に送信します。
<meta-data>
要素では AppWidgetProviderInfo
リソースを指定します。次の属性が必要です。
android:name
: メタデータ名を指定します。android.appwidget.provider
を使用して、データをAppWidgetProviderInfo
記述子として識別します。android:resource
:AppWidgetProviderInfo
リソースのロケーションを指定します。
AppWidgetProvider クラスを実装する
AppWidgetProvider
クラスは、ウィジェット ブロードキャストを処理するコンビニエンス クラスとして BroadcastReceiver
を拡張します。ウィジェットが更新、削除、有効化、無効化されたときなど、ウィジェットに関連するイベント ブロードキャストのみを受け取ります。これらのブロードキャスト イベントが発生すると、次の AppWidgetProvider
メソッドが呼び出されます。
onUpdate()
- これは、
AppWidgetProviderInfo
のupdatePeriodMillis
属性で定義された間隔でウィジェットを更新するために呼び出されます。詳しくは、このページのその他のウィジェット属性を説明する表をご覧ください。 - このメソッドは、ユーザーがウィジェットを追加したときにも呼び出されるため、
View
オブジェクトのイベント ハンドラの定義や、ウィジェットに表示するデータを読み込むジョブの開始などの重要な設定を行います。ただし、configuration_optional
フラグを指定せずに構成アクティビティを宣言すると、このメソッドは、ユーザーがウィジェットを追加したときには呼び出されませんが、後続の更新では呼び出されます。構成の完了時に最初の更新を行うのは、構成アクティビティの役割です。詳しくは、ユーザーにアプリ ウィジェットの設定を許可するをご覧ください。 - 最も重要なコールバックは
onUpdate()
です。詳細については、このページのonUpdate()
クラスを使用してイベントを処理するをご覧ください。 onAppWidgetOptionsChanged()
このメソッドは、ウィジェットが最初に配置されるときと、ウィジェットのサイズが変更されるたびに呼び出されます。このコールバックを使用して、ウィジェットのサイズ範囲に基づいてコンテンツを表示または非表示にします。サイズ範囲(Android 12 以降では、ウィジェット インスタンスが使用できるサイズのリスト)を取得するには、
getAppWidgetOptions()
を呼び出します。これにより、以下を含むBundle
が返されます。OPTION_APPWIDGET_MIN_WIDTH
: ウィジェット インスタンスの幅の下限を dp 単位で指定します。OPTION_APPWIDGET_MIN_HEIGHT
: ウィジェット インスタンスの高さの下限を dp 単位で指定します。OPTION_APPWIDGET_MAX_WIDTH
: ウィジェット インスタンスの幅の上限を dp 単位で指定します。OPTION_APPWIDGET_MAX_HEIGHT
: ウィジェット インスタンスの高さの上限を dp 単位で指定します。OPTION_APPWIDGET_SIZES
: ウィジェット インスタンスが取得できるサイズ(List<SizeF>
)のリストが dp 単位で格納されます。Android 12 で導入されました。
onDeleted(Context, int[])
このメソッドは、ウィジェットがウィジェット ホストから削除されるたびに呼び出されます。
onEnabled(Context)
これは、ウィジェットのインスタンスが初めて作成されるときに呼び出されます。たとえば、ユーザーがウィジェットのインスタンスを 2 つ追加した場合、これは初回にのみ呼び出されます。新しいデータベースを開く必要がある場合や、すべてのウィジェット インスタンスに対して 1 回だけ行う別の設定を行う必要がある場合に適しています。
onDisabled(Context)
これは、ウィジェットの最後のインスタンスがウィジェット ホストから削除されたときに呼び出されます。ここでは、一時データベースの削除など、
onEnabled(Context)
で行った作業をクリーンアップします。onReceive(Context, Intent)
これはすべてのブロードキャストで、上記の各コールバック メソッドの前に呼び出されます。デフォルトの
AppWidgetProvider
実装はすべてのウィジェット ブロードキャストをフィルタリングし、必要に応じて前のメソッドを呼び出すため、通常はこのメソッドを実装する必要はありません。
AndroidManifest
で <receiver>
要素を使用して、AppWidgetProvider
クラスの実装をブロードキャスト レシーバとして宣言する必要があります。詳しくは、このページのマニフェストでウィジェットを宣言するをご覧ください。
onUpdate() クラスを使用してイベントを処理する
最も重要な AppWidgetProvider
コールバックは onUpdate()
です。configuration_optional
フラグを指定せずに構成アクティビティを使用する場合を除き、各ウィジェットがホストに追加されたときに呼び出されるためです。ウィジェットがユーザー操作イベントを受け入れる場合は、このコールバックにイベント ハンドラを登録します。ウィジェットが一時ファイルやデータベースを作成しない場合や、クリーンアップが必要な他の作業を実行しない場合は、onUpdate()
のみを定義する必要があります。
たとえば、タップ時にアクティビティを起動するボタンを備えたウィジェットが必要な場合は、次のような AppWidgetProvider
の実装を使用できます。
Kotlin
class ExampleAppWidgetProvider : AppWidgetProvider() { override fun onUpdate( context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray ) { // Perform this loop procedure for each widget that belongs to this // provider. appWidgetIds.forEach { appWidgetId -> // Create an Intent to launch ExampleActivity. val pendingIntent: PendingIntent = PendingIntent.getActivity( /* context = */ context, /* requestCode = */ 0, /* intent = */ Intent(context, ExampleActivity::class.java), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE ) // Get the layout for the widget and attach an onClick listener to // the button. val views: RemoteViews = RemoteViews( context.packageName, R.layout.appwidget_provider_layout ).apply { setOnClickPendingIntent(R.id.button, pendingIntent) } // Tell the AppWidgetManager to perform an update on the current // widget. appWidgetManager.updateAppWidget(appWidgetId, views) } } }
Java
public class ExampleAppWidgetProvider extends AppWidgetProvider { public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { // Perform this loop procedure for each widget that belongs to this // provider. for (int i=0; i < appWidgetIds.length; i++) { int appWidgetId = appWidgetIds[i]; // Create an Intent to launch ExampleActivity Intent intent = new Intent(context, ExampleActivity.class); PendingIntent pendingIntent = PendingIntent.getActivity( /* context = */ context, /* requestCode = */ 0, /* intent = */ intent, /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE ); // Get the layout for the widget and attach an onClick listener to // the button. RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout); views.setOnClickPendingIntent(R.id.button, pendingIntent); // Tell the AppWidgetManager to perform an update on the current app // widget. appWidgetManager.updateAppWidget(appWidgetId, views); } } }
この AppWidgetProvider
は onUpdate()
メソッドのみを定義し、それを使用して Activity
を起動し、setOnClickPendingIntent(int,
PendingIntent)
を使用してウィジェットのボタンにアタッチする PendingIntent
を作成します。これには、appWidgetIds
の各エントリを反復処理するループが含まれています。これは、このプロバイダによって作成された各ウィジェットを識別する ID の配列です。ユーザーがウィジェットのインスタンスを複数作成すると、それらはすべて同時に更新されます。ただし、ウィジェットのすべてのインスタンスに対して管理される updatePeriodMillis
スケジュールは 1 つのみです。たとえば、更新スケジュールが 2 時間ごとに定義され、ウィジェットの 2 番目のインスタンスが最初のインスタンスの 1 時間後に追加された場合、最初のインスタンスによって定義された期間に両方とも更新され、2 番目の更新期間は無視されます。どちらも 1 時間ごとではなく 2 時間ごとに更新されます。
詳しくは、ExampleAppWidgetProvider.java
サンプルクラスをご覧ください。
ウィジェット ブロードキャスト インテントを受け取る
AppWidgetProvider
はコンビニエンス クラスです。ウィジェットのブロードキャストを直接受信する場合は、独自の BroadcastReceiver
を実装するか、onReceive(Context,Intent)
コールバックをオーバーライドします。注意が必要なインテントは次のとおりです。
ACTION_APPWIDGET_UPDATE
ACTION_APPWIDGET_DELETED
ACTION_APPWIDGET_ENABLED
ACTION_APPWIDGET_DISABLED
ACTION_APPWIDGET_OPTIONS_CHANGED
ウィジェット レイアウトを作成する
ウィジェットの初期レイアウトを XML で定義し、プロジェクトの res/layout/
ディレクトリに保存する必要があります。詳しくは、設計ガイドラインをご覧ください。
レイアウトに精通していれば、ウィジェット レイアウトは簡単に作成できます。ただし、ウィジェットのレイアウトは RemoteViews
に基づいているため、あらゆる種類のレイアウトまたはビュー ウィジェットがサポートされているわけではありません。RemoteViews
でサポートされているビューのカスタムビューまたはサブクラスは使用できません。
RemoteViews
は ViewStub
もサポートしています。これは目に見えないゼロサイズの View
で、これを使用するとレイアウト リソースのインフレートを実行時に遅延できます。
ステートフル動作のサポート
Android 12 では、次の既存のコンポーネントを使用したステートフル動作のサポートが追加されています。
このウィジェットはまだステートレスであるため、アプリが状態を保存し、状態変化イベントを登録できるようにする必要があります。
次のコードサンプルは、これらのコンポーネントを実装する方法を示しています。
Kotlin
// 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) )
Java
// 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 12 では、ウィジェットの角の丸みを設定する次のシステム パラメータが導入されています。
system_app_widget_background_radius
: ウィジェットの背景の角の半径。28 dp 以下にする必要があります。system_app_widget_inner_radius
: ウィジェット内のビューの隅の半径。これは、背景の半径よりもちょうど 8 dp 小さくなるため、8 dp のパディングを使用した場合に適切に配置されます。
次の例は、system_app_widget_background_radius
をウィジェットの角に、system_app_widget_inner_radius
をウィジェット内のビューに使用したウィジェットを示しています。
1 ウィジェットの角。
2 ウィジェット内のビューの角。
角の丸みに関する重要な考慮事項
- サードパーティ ランチャーとデバイス メーカーは、
system_app_widget_background_radius
パラメータを 28 dp 未満にオーバーライドできます。system_app_widget_inner_radius
パラメータは、常にsystem_app_widget_background_radius
の値より 8 dp 小さくなります。 - ウィジェットで
@android:id/background
を使用していない場合、または枠線に基づいてコンテンツをクリップする背景を定義している場合(android:clipToOutline
をtrue
に設定している場合)、ランチャーは背景を自動的に識別し、最大 16 dp の角の丸い長方形を使用してウィジェットをクリップします。ウィジェットが Android 12 に対応していることを確認するをご覧ください。
以前のバージョンの Android とウィジェットとの互換性を確保するために、Android 12 では、カスタム属性を定義し、カスタムテーマを使用してオーバーライドすることをおすすめします。以下のサンプル XML ファイルをご覧ください。
/values/attrs.xml
<resources>
<attr name="backgroundRadius" format="dimension" />
</resources>
/values/styles.xml
<resources>
<style name="MyWidgetTheme">
<item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
</style>
</resources>
/values-31/styles.xml
<resources>
<style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
<item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
</style>
</resources>
/drawable/my_widget_background.xml
<shape xmlns:android="http://schemas.android.com/apk/res/android"
android:shape="rectangle">
<corners android:radius="?attr/backgroundRadius" />
...
</shape>
/layout/my_widget_layout.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
...
android:background="@drawable/my_widget_background" />