使用珍藏內容小工具

集合小工具可以專門顯示相同類型的許多元素,例如圖片庫應用程式中的圖片集合、新聞應用程式的文章,或通訊應用程式的訊息。集合小工具通常著重於兩種用途:瀏覽集合,以及開啟集合元素進入詳細資料檢視畫面。集合小工具可以垂直捲動。

這些小工具使用 RemoteViewsService 來顯示由遠端資料支援的集合,例如來自內容供應器。小工具會使用下列其中一種檢視畫面類型 (稱為「集合檢視畫面」) 顯示資料:

ListView
在垂直捲動清單中顯示項目的檢視畫面。
GridView
在二維捲動格線中顯示項目的檢視畫面。
StackView
堆疊資訊卡檢視畫面 (用途與 rolodex 類似) 可讓使用者將前卡上下撥動,分別查看上一張或下一張資訊卡。
AdapterViewFlipper
轉接程式採用的簡易 ViewAnimator 可在兩個以上的檢視畫面之間建立動畫。系統一次只會顯示一個孩童。

這些集合檢視畫面會顯示遠端資料支援的集合,因此會使用 Adapter,將使用者介面繫結至資料。Adapter 會將一組資料中的個別項目繫結至個別的 View 物件。

這些集合檢視畫面受轉接程式支援,因此 Android 架構必須包含額外架構,才能在小工具中使用。在小工具的結構定義中,Adapter 會替換為 RemoteViewsFactory,這是 Adapter 介面周圍的精簡包裝函式。當要求取得集合中的特定項目時,RemoteViewsFactory 會為集合建立並傳回項目做為 RemoteViews 物件。如要在小工具中加入集合檢視畫面,請實作 RemoteViewsServiceRemoteViewsFactory

RemoteViewsService 是一項服務,可讓遠端轉接器要求 RemoteViews 物件。RemoteViewsFactory 是集合檢視畫面 (例如 ListViewGridViewStackView) 與該檢視畫面基礎資料之間的轉接介面。以下是實作這項服務與介面的樣板程式碼範例:StackWidget 範例

Kotlin

class StackWidgetService : RemoteViewsService() {

    override fun onGetViewFactory(intent: Intent): RemoteViewsFactory {
        return 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.

}

Java

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {

// See the RemoteViewsFactory API reference for the full list of methods to
// implement.

}

範例應用程式

本節的程式碼片段也擷取自 StackWidget 範例

圖 1. StackWidget

這個範例含有 10 個檢視畫面的堆疊,其中的值會顯示 0 到 9。範例小工具有下列主要行為:

  • 使用者可以垂直翻轉小工具的頂端檢視畫面,顯示下一個或上一個檢視畫面。這是內建的 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 檔案的主要要求,就是包含其中一個集合檢視畫面:ListViewGridViewStackViewAdapterViewFlipper。以下是 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 範例只有一個項目版面配置檔案 widget_item.xml

含有集合的小工具的 AppWidgetProvider 類別

和一般小工具一樣,AppWidgetProvider 子類別中的大量程式碼通常位於 onUpdate()。建立含有集合的小工具時,實作 onUpdate() 的主要差異在於您必須呼叫 setRemoteAdapter()。這會告知集合檢視畫面該從何處取得資料。接著,RemoteViewsService 可以傳回 RemoteViewsFactory 的實作內容,小工具則可提供適當的資料。呼叫此方法時,請傳遞指向 RemoteViewsService 實作項目的意圖,以及指定要更新小工具的小工具 ID。

以下舉例說明 StackWidget 範例如何實作 onUpdate() 回呼方法,將 RemoteViewsService 設為小工具集合的遠端轉接器:

Kotlin

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)
}

Java

public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
    // Update each of the widgets with the remote adapter.
    for (int i = 0; i < appWidgetIds.length; ++i) {

        // Set up the intent that starts the StackViewService, which
        // provides the views for this collection.
        Intent intent = new Intent(context, StackWidgetService.class);
        // Add the widget ID to the intent extras.
        intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
        intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
        // Instantiate the RemoteViews object for the widget layout.
        RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
        // 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.
        views.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.
        views.setEmptyView(R.id.stack_view, R.id.empty_view);

        // Do additional processing specific to this widget.

        appWidgetManager.updateAppWidget(appWidgetIds[i], views);
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds);
}

保存資料

如本頁所述,RemoteViewsService 子類別提供用來填入遠端集合檢視畫面的 RemoteViewsFactory

具體而言,請執行下列步驟:

  1. 子類別 RemoteViewsServiceRemoteViewsService 是遠端轉接器可透過此服務要求 RemoteViews 的服務。

  2. RemoteViewsService 子類別中,加入實作 RemoteViewsFactory 介面的類別。RemoteViewsFactory 是遠端集合檢視畫面 (例如 ListViewGridViewStackView) 與該檢視畫面基礎資料之間的轉換器介面。您的實作負責為資料集中的每個項目建立 RemoteViews 物件。這個介面是 Adapter 周圍的精簡包裝函式。

您無法依賴服務的單一執行個體或服務包含的任何資料來保留。除非是靜態資料,否則請不要將資料儲存在 RemoteViewsService 中。如果想保留小工具的資料,最佳做法是使用 ContentProvider,其中資料會留在程序生命週期之外。舉例來說,雜貨店小工具可將每個雜貨清單項目的狀態儲存在永久位置 (例如 SQL 資料庫)。

RemoteViewsService 實作的主要內容為 RemoteViewsFactory,如下一節所述。

RemoteViewsFactory 介面

實作 RemoteViewsFactory 介面的自訂類別可為小工具提供集合內項目的資料。為此,系統會將小工具項目 XML 版面配置檔案與資料來源結合。資料來源可以是資料庫到簡單的陣列。在 StackWidget 範例中,資料來源是 WidgetItems 的陣列。RemoteViewsFactory 可做為轉接介面,將資料對應至遠端集合檢視畫面。

您必須為 RemoteViewsFactory 子類別實作的兩個最重要的方法為 onCreate()getViewAt()

首次建立工廠時,系統會呼叫 onCreate()。您可以在這裡設定資料來源的任何連線或遊標。舉例來說,StackWidget 範例使用 onCreate() 初始化 WidgetItem 物件的陣列。小工具啟用時,系統會使用物件在陣列中的索引位置存取這些物件,並顯示物件包含的文字。

以下是 StackWidget 範例 RemoteViewsFactory 實作內容摘錄,其中顯示 onCreate() 方法的部分:

Kotlin

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!") }
        ...
    }
    ...
}

Java

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int REMOTE_VIEW_COUNT = 10;
    private List<WidgetItem> widgetItems = new ArrayList<WidgetItem>();

    public void onCreate() {
        // In onCreate(), setup 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.
        for (int i = 0; i < REMOTE_VIEW_COUNT; i++) {
            widgetItems.add(new WidgetItem(i + "!"));
        }
        ...
    }
...

RemoteViewsFactory 方法 getViewAt() 會回傳 RemoteViews 物件,該物件會對應資料集中指定 position 的資料。以下摘錄 StackWidget 範例的 RemoteViewsFactory 實作內容:

Kotlin

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)
    }
}

Java

public RemoteViews getViewAt(int position) {
    // Construct a remote views item based on the widget item XML file
    // and set the text based on the position.
    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_item);
    views.setTextViewText(R.id.widget_item, widgetItems.get(position).text);
    return views;
}

為個別項目新增行為

上一節說明如何將資料繫結至小工具集合。但如果您想為集合檢視畫面中的個別項目新增動態行為,該怎麼做?

如「使用 onUpdate() 類別處理事件」一文所述,您通常會使用 setOnClickPendingIntent() 設定物件的點擊行為,例如造成按鈕啟動 Activity。但這種做法不允許用於個別集合項目中的子檢視畫面。舉例來說,您可以使用 setOnClickPendingIntent() 在 Gmail 小工具中設定全域按鈕,用於啟動應用程式,而不是個別清單項目。

請改為使用 setOnClickFillInIntent(),為集合中的個別項目新增點擊行為。包括為集合檢視畫面設定待處理意圖範本,然後透過 RemoteViewsFactory 為集合中的每個項目設定填入意圖。

本節會使用 StackWidget 範例,說明如何將行為新增至個別項目。在 StackWidget 範例中,如果使用者輕觸頂端檢視畫面,小工具會顯示「已輕觸的檢視畫面「n」Toast 訊息,其中「n」是觸控檢視畫面的索引 (位置)。這類廣告運作方式如下:

  • StackWidgetProvider (AppWidgetProvider 子類別) 會使用名為 TOAST_ACTION 的自訂動作建立待處理意圖。

  • 使用者輕觸檢視畫面時,意圖會啟動並廣播 TOAST_ACTION

  • 這個廣播訊息受到 StackWidgetProvider 類別的 onReceive() 方法攔截,小工具會顯示觸控式檢視畫面的 Toast 訊息。集合項目的資料是由 RemoteViewsFactory 透過 RemoteViewsService 提供。

設定待處理意圖範本

StackWidgetProvider (AppWidgetProvider 子類別) 會設定待處理意圖。集合的個別項目無法設定自己的待處理意圖。相反地,集合會設定一個待處理意圖範本,而個別項目會設定填入意圖,為每個項目建立專屬行為。

這個類別也會接收使用者輕觸檢視畫面時傳送的廣播。此方法會在其 onReceive() 方法中處理此事件。如果意圖的動作是 TOAST_ACTION,小工具會為目前的檢視畫面顯示 Toast 訊息。

Kotlin

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))

                PendingIntent.getBroadcast(context, 0, this, PendingIntent.FLAG_UPDATE_CURRENT)
            }
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent)

            appWidgetManager.updateAppWidget(appWidgetId, rv)
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds)
    }
}

Java

public class StackWidgetProvider extends AppWidgetProvider {
    public static final String TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION";
    public static final String EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM";

    ...

    // 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
    public void onReceive(Context context, Intent intent) {
        AppWidgetManager mgr = AppWidgetManager.getInstance(context);
        if (intent.getAction().equals(TOAST_ACTION)) {
            int appWidgetId = 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.
            int viewIndex = intent.getIntExtra(EXTRA_ITEM, 0);
            Toast.makeText(context, "Touched view " + viewIndex, Toast.LENGTH_SHORT).show();
        }
        super.onReceive(context, intent);
    }

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Update each of the widgets with the remote adapter.
        for (int i = 0; i < appWidgetIds.length; ++i) {

            // Sets up the intent that points to the StackViewService that
            // provides the views for this collection.
            Intent intent = new Intent(context, StackWidgetService.class);
            intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            // When intents are compared, the extras are ignored, so embed
            // the extras into the data so that the extras are not
            // ignored.
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
            rv.setRemoteAdapter(appWidgetIds[i], 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.
            rv.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.
            Intent toastIntent = new Intent(context, StackWidgetProvider.class);
            // Set the action for the intent.
            // When the user touches a particular view, it has the effect of
            // broadcasting TOAST_ACTION.
            toastIntent.setAction(StackWidgetProvider.TOAST_ACTION);
            toastIntent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            PendingIntent toastPendingIntent = PendingIntent.getBroadcast(context, 0, toastIntent,
                PendingIntent.FLAG_UPDATE_CURRENT);
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent);

            appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds);
    }
}

設定填入意圖

RemoteViewsFactory 必須針對集合中的每個項目設定填入意圖。這有助於區別特定項目的個別點擊動作。接著,填入意圖會與 PendingIntent 範本結合,判定輕觸項目時要執行的最終意圖。

Kotlin

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)
            ...
        }
    }
    ...
}

Java

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int count = 10;
    private List<WidgetItem> widgetItems = new ArrayList<WidgetItem>();
    private Context context;
    private int appWidgetId;

    public StackRemoteViewsFactory(Context context, Intent intent) {
        this.context = context;
        appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
    }

    // Initialize the data set.
    public void 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.
        for (int i = 0; i < count; i++) {
            widgetItems.add(new WidgetItem(i + "!"));
        }
        ...
    }

    // Given the position (index) of a WidgetItem in the array, use the
    // item's text value in combination with the widget item XML file to
    // construct a RemoteViews object.
    public RemoteViews getViewAt(int position) {
        // Position always ranges from 0 to getCount() - 1.

        // Construct a RemoteViews item based on the widget item XML
        // file and set the text based on the position.
        RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_item);
        rv.setTextViewText(R.id.widget_item, widgetItems.get(position).text);

        // Set a fill-intent to fill in the pending
        // intent template that is set on the collection view in
        // StackWidgetProvider.
        Bundle extras = new Bundle();
        extras.putInt(StackWidgetProvider.EXTRA_ITEM, position);
        Intent fillInIntent = new Intent();
        fillInIntent.putExtras(extras);
        // Make it possible to distinguish the individual on-click
        // action of a given item.
        rv.setOnClickFillInIntent(R.id.widget_item, fillInIntent);

        // Return the RemoteViews object.
        return rv;
    }
    ...
}

持續更新集合資料

圖 2 說明使用集合的小工具更新流程。呈現小工具程式碼如何與 RemoteViewsFactory 互動,以及如何觸發更新:

圖 2. 在更新期間與 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()

這個方法不僅能夠更輕鬆地填入轉接程式,當使用者向下捲動清單顯示新項目時,也可避免填入新項目所需的時間。只要集合項目組合很少,最好採用這種設定轉接器。不過,舉例來說,如果您的集合包含許多 Bitmaps 傳遞至 setImageViewBitmap,這個方法就無法正常運作。

如果集合未使用常數版面配置 (也就是有些項目有時只會顯示),請使用 setViewTypeCount 指定集合可包含的不重複版面配置數量上限。以便在應用程式小工具更新時重複使用轉接程式。

以下範例說明如何實作簡化的 RemoteViews 集合。

Kotlin

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()
)

Java

List<Integer> itemLayouts = Arrays.asList(
    R.layout.item_type_1,
    R.layout.item_type_2,
    ...
);

remoteView.setRemoteAdapter(
    R.id.list_view,
    new RemoteViews.RemoteCollectionItems.Builder()
        .addItem(/* id= */ ID_1, new RemoteViews(context.getPackageName(), R.layout.item_type_1))
        .addItem(/* id= */ ID_2, new RemoteViews(context.getPackageName(), R.layout.item_type_2))
        ...
        .setViewTypeCount(itemLayouts.size())
        .build()
);