コレクション ウィジェットは、同じタイプの多数の要素を表示することに特化しています。たとえば、写真アプリの写真のコレクション、ニュースアプリの記事、コミュニケーション アプリのメッセージなどです。コレクション ウィジェットは通常、コレクションの閲覧と、コレクションの要素を開いて詳細ビューを表示するという 2 つのユースケースに重点を置いています。コレクション ウィジェットは上下にスクロールできます。
これらのウィジェットは、RemoteViewsService を使用して、コンテンツ プロバイダなどからのリモートデータに基づくコレクションを表示します。ウィジェットは、次のいずれかのビュータイプ（コレクション ビュー）を使用してデータを表示します。
ListView: 垂直方向にスクロールするリストにアイテムを表示するビュー。
GridView: 2 次元のスクロール グリッドにアイテムを表示するビュー。
StackView: 積み重ねられたカードビュー（ローロデックスのようなもの）。ユーザーは、前面のカードを上下にフリックして、それぞれ前後のカードを表示できます。
AdapterViewFlipper: 2 つ以上のビュー間でアニメーション化する、アダプターを基盤とする ViewAnimator。一度に表示される子は 1 つだけです。
これらのコレクション ビューは、リモートデータに基づくコレクションを表示するため、Adapter を使用してユーザー インターフェースをデータにバインドします。Adapter は、データセットの個々のアイテムを個々の View オブジェクトにバインドします。
また、これらのコレクション ビューはアダプターによってサポートされているため、Android フレームワークには、ウィジェットでの使用をサポートするための追加のアーキテクチャが含まれている必要があります。ウィジェットのコンテキストでは、Adapter は RemoteViewsFactory に置き換えられます。これは、Adapter インターフェースの薄いラッパーです。コレクション内の特定のアイテムがリクエストされると、RemoteViewsFactory はコレクションのアイテムを RemoteViews オブジェクトとして作成して返します。ウィジェットにコレクション ビューを含めるには、RemoteViewsService と RemoteViewsFactory を実装します。
RemoteViewsService は、リモート アダプタが RemoteViews オブジェクトをリクエストできるようにするサービスです。RemoteViewsFactory は、コレクション ビュー（ListView、GridView、StackView など）とそのビューの基盤となるデータとの間のアダプターのインターフェースです。StackWidget サンプルから、このサービスとインターフェースを実装するボイラープレート コードの例を次に示します。
class StackWidgetService : RemoteViewsService() { override fun onGetViewFactory(intent: Intent): RemoteViewsFactory = StackRemoteViewsFactory(this.applicationContext, intent) } class StackRemoteViewsFactory( private val context: Context, intent: Intent ) : RemoteViewsService.RemoteViewsFactory { // See the RemoteViewsFactory API reference for the full list of methods to implement. }
サンプル アプリケーション
このセクションのコードの抜粋も、StackWidget サンプルから引用したものです。
StackWidget。このサンプルは、0 から 9 までの値を表示する 10 個のビューのスタックで構成されています。サンプル ウィジェットの主な動作は次のとおりです。
ユーザーは、ウィジェットの上部ビューを垂直方向にフリックして、次または前のビューを表示できます。これは
StackViewの組み込みの動作です。ユーザーの操作なしで、ウィジェットはスライドショーのようにビューを順番に自動的に進めます。これは、
res/xml/stackwidgetinfo.xmlファイルのandroid:autoAdvanceViewId="@id/stack_view"設定によるものです。この設定はビュー ID に適用されます。この例では、スタックビューのビュー ID です。ユーザーがトップビューをタップすると、ウィジェットに
Toastメッセージ「Touched view n」が表示されます。ここで、n はタップされたビューのインデックス（位置）です。動作の実装方法の詳細については、個々のアイテムに動作を追加するセクションをご覧ください。
コレクションを含むウィジェットを実装する
コレクションを含むウィジェットを実装するには、任意のウィジェットを実装する手順に沿って操作し、さらにマニフェストの変更、ウィジェット レイアウトへのコレクション ビューの追加、AppWidgetProvider サブクラスの変更を行います。
コレクションを含むウィジェットのマニフェスト
マニフェストでウィジェットを宣言するに記載されている要件に加えて、コレクションを含むウィジェットを RemoteViewsService にバインドできるようにする必要があります。これを行うには、マニフェスト ファイルで BIND_REMOTEVIEWS 権限を使用してサービスを宣言します。これにより、他のアプリケーションがウィジェットのデータに自由にアクセスできなくなります。
たとえば、RemoteViewsService を使用してコレクション ビューにデータを入力するウィジェットを作成する場合、マニフェスト エントリは次のようになります。
<service android:name="MyWidgetService"
android:permission="android.permission.BIND_REMOTEVIEWS" />
この例では、android:name="MyWidgetService" は RemoteViewsService のサブクラスを指します。
コレクションを含むウィジェットのレイアウト
ウィジェット レイアウト XML ファイルの主な要件は、コレクション ビュー（ListView、GridView、StackView、AdapterViewFlipper のいずれか）を含めることです。StackWidget サンプルの widget_layout.xml ファイルは次のとおりです。
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="match_parent"> <StackView android:id="@+id/stack_view" android:layout_width="match_parent" android:layout_height="match_parent" android:gravity="center" android:loopViews="true" /> <TextView android:id="@+id/empty_view" android:layout_width="match_parent" android:layout_height="match_parent" android:gravity="center" android:background="@drawable/widget_item_background" android:textColor="#ffffff" android:textStyle="bold" android:text="@string/empty_view_text" android:textSize="20sp" /> </FrameLayout>
空のビューは、空のビューが空の状態を表すコレクション ビューの兄弟である必要があります。
ウィジェット全体のレイアウト ファイルに加えて、コレクション内の各アイテムのレイアウトを定義する別のレイアウト ファイルを作成します。たとえば、書籍のコレクション内の各書籍のレイアウトです。StackWidget サンプルには、アイテム レイアウト ファイルが 1 つ（widget_item.xml）しかありません。これは、すべてのアイテムが同じレイアウトを使用しているためです。
コレクションを含むウィジェットの AppWidgetProvider クラス
通常のウィジェットと同様に、AppWidgetProvider サブクラスのコードの大部分は通常、onUpdate() に配置されます。コレクションを含むウィジェットを作成する場合、onUpdate() の実装における主な違いは、setRemoteAdapter() を呼び出す必要があることです。これにより、コレクション ビューにデータの取得元が指示されます。
RemoteViewsService は RemoteViewsFactory の実装を返すことができ、ウィジェットは適切なデータを提供できます。このメソッドを呼び出すときは、RemoteViewsService の実装を指すインテントと、更新するウィジェットを指定するウィジェット ID を渡します。
たとえば、StackWidget サンプルでは、onUpdate() コールバック メソッドを実装して、RemoteViewsService をウィジェット コレクションのリモート アダプタとして設定しています。
override fun onUpdate( context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray ) { // Update each of the widgets with the remote adapter. appWidgetIds.forEach { appWidgetId -> // Set up the intent that starts the StackViewService, which // provides the views for this collection. val intent = Intent(context, StackWidgetService::class.java).apply { // Add the widget ID to the intent extras. putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME)) } // Instantiate the RemoteViews object for the widget layout. val views = RemoteViews(context.packageName, R.layout.widget_layout).apply { // Set up the RemoteViews object to use a RemoteViews adapter. // This adapter connects to a RemoteViewsService through the // specified intent. // This is how you populate the data. setRemoteAdapter(R.id.stack_view, intent) // The empty view is displayed when the collection has no items. // It must be in the same layout used to instantiate the // RemoteViews object. setEmptyView(R.id.stack_view, R.id.empty_view) } // Do additional processing specific to this widget. appWidgetManager.updateAppWidget(appWidgetId, views) } super.onUpdate(context, appWidgetManager, appWidgetIds) }
データを永続化する
このページで説明するように、RemoteViewsService サブクラスは、リモート コレクション ビューにデータを入力するために使用される RemoteViewsFactory を提供します。
具体的には、次の手順を行います。
サブクラス
RemoteViewsService。RemoteViewsServiceは、リモート アダプターがRemoteViewsをリクエストできるサービスです。RemoteViewsServiceサブクラスに、RemoteViewsFactoryインターフェースを実装するクラスを含めます。RemoteViewsFactoryは、リモート コレクション ビュー（ListView、GridView、StackViewなど）とそのビューの基盤となるデータとの間のアダプターのインターフェースです。実装では、データセット内の各アイテムにRemoteViewsオブジェクトを作成する必要があります。このインターフェースは、Adapterの薄いラッパーです。
サービスの単一インスタンスや、それに含まれるデータが永続化されるとは限りません。静的データでない限り、RemoteViewsService にデータを保存しないでください。ウィジェットのデータを保持する場合は、プロセスのライフサイクルを超えてデータが保持される ContentProvider を使用することをおすすめします。たとえば、食料品店のウィジェットは、各食料品リストアイテムの状態を SQL データベースなどの永続的な場所に保存できます。
RemoteViewsService 実装の主な内容は、次のセクションで説明する RemoteViewsFactory です。
RemoteViewsFactory インターフェース
RemoteViewsFactory インターフェースを実装するカスタムクラスは、コレクション内のアイテムのデータをウィジェットに提供します。この処理を行うために、ウィジェット アイテムの XML レイアウト ファイルとデータソースを組み合わせます。このデータソースは、データベースから配列まで、何でもかまいません。StackWidget サンプルでは、データソースは WidgetItems の配列です。RemoteViewsFactory は、データをリモート コレクション ビューに接着するアダプターとして機能します。
RemoteViewsFactory サブクラスに実装する必要がある最も重要なメソッドは、onCreate() と getViewAt() です。
システムは、ファクトリを初めて作成するときに onCreate() を呼び出します。ここで、データソースへの接続やカーソルを設定します。たとえば、StackWidget サンプルでは、onCreate() を使用して WidgetItem オブジェクトの配列を初期化します。ウィジェットがアクティブになると、システムは配列内のインデックス位置を使用してこれらのオブジェクトにアクセスし、オブジェクトに含まれるテキストを表示します。
以下は、StackWidget サンプルの RemoteViewsFactory 実装からの抜粋で、onCreate() メソッドの一部を示しています。
private const val REMOTE_VIEW_COUNT: Int = 10 class StackRemoteViewsFactory( private val context: Context ) : RemoteViewsService.RemoteViewsFactory { private lateinit var widgetItems: List<WidgetItem> override fun onCreate() { // In onCreate(), set up any connections or cursors to your data // source. Heavy lifting, such as downloading or creating content, // must be deferred to onDataSetChanged() or getViewAt(). Taking // more than 20 seconds on this call results in an ANR. widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") } } }
RemoteViewsFactory メソッド getViewAt() は、データセット内の指定された position のデータに対応する RemoteViews オブジェクトを返します。StackWidget サンプルの RemoteViewsFactory 実装からの抜粋を次に示します。
override fun getViewAt(position: Int): RemoteViews { // Construct a remote views item based on the widget item XML file // and set the text based on the position. return RemoteViews(context.packageName, R.layout.widget_item).apply { setTextViewText(R.id.widget_item, widgetItems[position].text) } }
個々のアイテムに動作を追加する
前のセクションでは、データをウィジェット コレクションにバインドする方法について説明しました。しかし、コレクション ビューの個々のアイテムに動的な動作を追加したい場合はどうすればよいでしょうか。
onUpdate() クラスでイベントを処理するで説明したように、通常は setOnClickPendingIntent() を使用して、オブジェクトのクリック動作（ボタンで Activity を起動するなど）を設定します。ただし、この方法は、個々のコレクション アイテムの子ビューでは使用できません。たとえば、setOnClickPendingIntent() を使用して、アプリを起動するグローバル ボタンを Gmail ウィジェットに設定できますが、個々のリストアイテムには設定できません。
代わりに、コレクション内の個々のアイテムにクリック動作を追加するには、setOnClickFillInIntent() を使用します。コレクション ビューのペンディング インテント テンプレートを設定し、RemoteViewsFactory を使用してコレクション内の各アイテムにフィルイン インテントを設定します。
このセクションでは、StackWidget サンプルを使用して、個々のアイテムに動作を追加する方法について説明します。StackWidget サンプルでは、ユーザーがトップビューをタップすると、ウィジェットに Toast メッセージ「Touched view n」が表示されます。ここで、n はタップされたビューのインデックス（位置）です。次のような仕組みになっています。
StackWidgetProvider（AppWidgetProviderサブクラス）は、TOAST_ACTIONというカスタム アクションを含むペンディング インテントを作成します。ユーザーがビューをタップすると、インテントが起動し、
TOAST_ACTIONがブロードキャストされます。このブロードキャストは、
StackWidgetProviderクラスのonReceive()メソッドによってインターセプトされ、ウィジェットはタップされたビューのToastメッセージを表示します。コレクション アイテムのデータは、RemoteViewsServiceを介してRemoteViewsFactoryによって提供されます。
ペンディング インテント テンプレートを設定する
StackWidgetProvider（AppWidgetProvider サブクラス）は、ペンディング インテントを設定します。コレクションの個々のアイテムに独自のペンディング インテントを設定することはできません。代わりに、コレクション全体でペンディング インテント テンプレートを設定し、個々のアイテムでフィルイン インテントを設定して、アイテムごとに固有の動作を作成します。
このクラスは、ユーザーがビューをタップしたときに送信されるブロードキャストも受信します。このイベントを onReceive() メソッドで処理します。インテントのアクションが TOAST_ACTION の場合、ウィジェットは現在のビューに Toast メッセージを表示します。
const val TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION" const val EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM" class StackWidgetProvider : AppWidgetProvider() { // ... // Called when the BroadcastReceiver receives an Intent broadcast. // Checks whether the intent's action is TOAST_ACTION. If it is, the // widget displays a Toast message for the current item. override fun onReceive(context: Context, intent: Intent) { val mgr: AppWidgetManager = AppWidgetManager.getInstance(context) if (intent.action == TOAST_ACTION) { val appWidgetId: Int = intent.getIntExtra( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID ) // EXTRA_ITEM represents a custom value provided by the Intent // passed to the setOnClickFillInIntent() method to indicate the // position of the clicked item. See StackRemoteViewsFactory in // Set the fill-in Intent for details. val viewIndex: Int = intent.getIntExtra(EXTRA_ITEM, 0) Toast.makeText(context, "Touched view $viewIndex", Toast.LENGTH_SHORT).show() } super.onReceive(context, intent) } override fun onUpdate( context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray ) { // Update each of the widgets with the remote adapter. appWidgetIds.forEach { appWidgetId -> // Sets up the intent that points to the StackViewService that // provides the views for this collection. val intent = Intent(context, StackWidgetService::class.java).apply { putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) // When intents are compared, the extras are ignored, so embed // the extra sinto the data so that the extras are not ignored. data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME)) } val rv = RemoteViews(context.packageName, R.layout.widget_layout).apply { setRemoteAdapter(R.id.stack_view, intent) // The empty view is displayed when the collection has no items. // It must be a sibling of the collection view. setEmptyView(R.id.stack_view, R.id.empty_view) } // This section makes it possible for items to have individualized // behavior. It does this by setting up a pending intent template. // Individuals items of a collection can't set up their own pending // intents. Instead, the collection as a whole sets up a pending // intent template, and the individual items set a fillInIntent // to create unique behavior on an item-by-item basis. val toastPendingIntent: PendingIntent = Intent( context, StackWidgetProvider::class.java ).run { // Set the action for the intent. // When the user touches a particular view, it has the effect of // broadcasting TOAST_ACTION. action = TOAST_ACTION putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME)) // The template must be mutable, because each item fills in its // own extras through setOnClickFillInIntent(). PendingIntent.getBroadcast( context, 0, this, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE ) } rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent) appWidgetManager.updateAppWidget(appWidgetId, rv) } super.onUpdate(context, appWidgetManager, appWidgetIds) } }
入力インテントを設定する
RemoteViewsFactory は、コレクション内の各アイテムにフィルイン インテントを設定する必要があります。これにより、特定のアイテムの個々のクリック時アクションを区別できます。次に、このインテントが PendingIntent テンプレートと組み合わされ、アイテムがタップされたときに実行される最終的なインテントが決定されます。
private const val REMOTE_VIEW_COUNT: Int = 10 class StackRemoteViewsFactory( private val context: Context, intent: Intent ) : RemoteViewsService.RemoteViewsFactory { private lateinit var widgetItems: List<WidgetItem> private val appWidgetId: Int = intent.getIntExtra( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID ) override fun onCreate() { // In onCreate(), set up any connections or cursors to your data source. // Heavy lifting, such as downloading or creating content, must be // deferred to onDataSetChanged() or getViewAt(). Taking more than 20 // seconds on this call results in an ANR. widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") } // ... } // ... override fun getViewAt(position: Int): RemoteViews { // Construct a remote views item based on the widget item XML file // and set the text based on the position. return RemoteViews(context.packageName, R.layout.widget_item).apply { setTextViewText(R.id.widget_item, widgetItems[position].text) // Set a fill-intent to fill in the pending intent template. // that is set on the collection view in StackWidgetProvider. val fillInIntent = Intent().apply { Bundle().also { extras -> extras.putInt(EXTRA_ITEM, position) putExtras(extras) } } // Make it possible to distinguish the individual on-click // action of a given item. setOnClickFillInIntent(R.id.widget_item, fillInIntent) // ... } } // ... }
コレクション データを最新の状態に保つ
図 2 は、コレクションを使用するウィジェットの更新フローを示しています。この図は、ウィジェット コードが RemoteViewsFactory とどのようにやり取りするか、また、更新をトリガーする方法を示しています。
RemoteViewsFactory とのやり取り。コレクションを使用するウィジェットは、ユーザーに最新のコンテンツを提供できます。たとえば、Gmail ウィジェットを使用すると、ユーザーは受信トレイのスナップショットを確認できます。これを可能にするには、RemoteViewsFactory とコレクション ビューをトリガーして、新しいデータを取得して表示します。
これを行うには、AppWidgetManager を使用して notifyAppWidgetViewDataChanged() を呼び出します。この呼び出しにより、RemoteViewsFactory オブジェクトの onDataSetChanged() メソッドへのコールバックが発生し、新しいデータを取得できるようになります。
onDataSetChanged() コールバック内で、処理負荷の高いオペレーションを同期的に実行できます。この呼び出しは、メタデータまたはビューデータが RemoteViewsFactory から取得される前に完了します。getViewAt() メソッド内で処理負荷の高いオペレーションを実行することもできます。この呼び出しに時間がかかる場合、RemoteViewsFactory オブジェクトの getLoadingView() メソッドで指定された読み込みビューが、戻るまでコレクション ビューの対応する位置に表示されます。
RemoteCollectionItems を使用してコレクションを直接渡す
Android 12（API レベル 31）では、setRemoteAdapter(int viewId,
RemoteViews.RemoteCollectionItems
items) メソッドが追加されました。このメソッドを使用すると、アプリはコレクション ビューにデータを入力するときにコレクションを直接渡すことができます。このメソッドを使用してアダプターを設定すると、RemoteViewsFactory を実装する必要がなくなり、notifyAppWidgetViewDataChanged() を呼び出す必要もなくなります。
このアプローチでは、アダプターへの入力が容易になるだけでなく、ユーザーがリストをスクロールして新しいアイテムを表示する際に、新しいアイテムの入力に伴うレイテンシも解消されます。コレクション アイテムのセットが比較的小さい場合は、この方法でアダプターを設定することをおすすめします。ただし、たとえば、コレクションに setImageViewBitmap に渡される多数の Bitmaps が含まれている場合、このアプローチは適切に機能しません。
コレクションで一定のレイアウト セットを使用しない場合（一部のアイテムがときどきしか存在しない場合など）は、setViewTypeCount を使用して、コレクションに含めることができる一意のレイアウトの最大数を指定します。これにより、アプリ ウィジェットの更新全体でアダプターを再利用できます。
簡素化された RemoteViews コレクションを実装する方法の例を次に示します。
val itemLayouts = listOf( R.layout.item_type_1, R.layout.item_type_2, // ... ) remoteView.setRemoteAdapter( R.id.list_view, RemoteViews.RemoteCollectionItems.Builder() .addItem(/* id= */ ID_1, RemoteViews(context.packageName, R.layout.item_type_1)) .addItem(/* id= */ ID_2, RemoteViews(context.packageName, R.layout.item_type_2)) // ... .setViewTypeCount(itemLayouts.count()) .build() )