Koleksiyon widget'larını kullanma

Koleksiyon widget'ları, galeri uygulamasındaki resim koleksiyonları, haber uygulamasındaki makaleler veya iletişim uygulamasındaki mesajlar gibi aynı türden birçok öğeyi görüntüleme konusunda uzmandır. Koleksiyon widget'ları genellikle iki kullanım alanına odaklanır: koleksiyona göz atma ve koleksiyondaki bir öğeyi ayrıntı görünümünde açma. Koleksiyon widget'ları dikey olarak kaydırılabilir.

Bu widget'lar, içerik sağlayıcı gibi uzak verilerle desteklenen koleksiyonları görüntülemek için RemoteViewsService öğesini kullanır. Widget, widget'ı kullanarak toplama olarak bilinen görünüm türlerinden birini kullanan, görüntüleme:

ListView
Aşağıdaki öğeleri gösteren bir görünüm: Dikey olarak kayan bir liste.
GridView
Öğeleri iki boyutlu kaydırılabilir bir ızgarada gösteren görünüm.
StackView
Kullanıcının sırasıyla önceki veya sonraki kartı görmek için ön kartı yukarı ya da aşağı kaydırabileceği, kartların yığın halinde gösterildiği bir görünüm (kartvizit rulosu gibi).
AdapterViewFlipper
İki veya daha fazla görünüm arasında animasyonlu geçiş yapan, adaptör destekli basit bir ViewAnimator. Tek seferde yalnızca bir çocuk gösterilir.

Bu koleksiyon görünümleri, uzak verilerle desteklenen koleksiyonları görüntülediğinden kullanıcı arayüzlerini verilerine bağlamak için bir Adapter kullanırlar. Adapter, bir veri grubundaki bağımsız öğeleri bağımsız View nesnelerine bağlar.

Bu koleksiyon görünümleri bağdaştırıcılar tarafından desteklendiğinden, Android çerçevesi, widget'larda kullanılmalarını desteklemek için ek mimari içermelidir. Bağlam içinde bir widget'ın Adapter öğesinin yerine bir RemoteViewsFactory, Adapter arayüzünün etrafında ince bir sarmalayıcı olan. Koleksiyondaki belirli bir öğe istendiğinde RemoteViewsFactory, koleksiyon için öğeyi oluşturur ve RemoteViews nesnesi olarak döndürür. Widget'ınıza koleksiyon görünümü eklemek için RemoteViewsService ve RemoteViewsFactory öğelerini uygulayın.

RemoteViewsService, uzaktan adaptör isteğinde bulunabilen bir hizmettir. RemoteViews nesne. RemoteViewsFactory, bir koleksiyon görünümü (ör. ListView, GridView ve StackView) ile bu görünümün temel verileri arasındaki adaptör arayüzüdür. StackWidget örnek için bu hizmeti ve arayüzü uygulamak üzere kullanılan şablon kod örneğini aşağıda bulabilirsiniz:

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.

}

Örnek uygulama

Bu bölümdeki kod alıntıları da StackWidgetörneğinden alınmıştır:

Şekil 1. A StackWidget.

Bu örnek, sıfır değerlerini gösteren on görünümlük bir yığından oluşur dokuza kadar. Örnek widget'ın temel davranışları şu şekildedir:

  • Kullanıcı, sıradaki öğeyi görüntülemek için widget'taki üst görünümü dikey olarak çevirebilir. veya önceki görünüm. Bu, yerleşik bir StackView davranışıdır.

  • Widget, kullanıcı etkileşimi olmadan, slayt gösterisi gibi görüntülemelerini sırayla otomatik olarak ilerletir. Bunun nedeni, android:autoAdvanceViewId="@id/stack_view" res/xml/stackwidgetinfo.xml dosya Bu ayar, görüntüleme kimliği için geçerlidir. Bu örnek, yığın görünümünün görünüm kimliğidir.

  • Kullanıcı üst görünüme dokunursa widget, Toast mesajı "Dokunmatik görünüm n", burada: n, dokunulan görünümün dizinidir (konumu). Proje yönetiminin nasıl hakkında daha fazla bilgi edinmek için Kişiye davranış ekleme öğeler bölümüne bakın.

Widget'ları koleksiyonlarla uygulama

Bir widget'ı koleksiyonlarla uygulamak için herhangi bir widget'ı widget'ını ve ardından birkaç ek adımı takip edin: widget düzenine bir koleksiyon görünümü ekleyebilir ve mevcut görünümünüzde AppWidgetProvider alt sınıf.

Koleksiyonları olan widget'larla ilgili manifest

Manifest dosyasında widget beyan etme bölümünde listelenen koşulların yanı sıra, koleksiyon içeren widget'ların RemoteViewsService'nize bağlanmasını mümkün kılmanız gerekir. Bunu, manifest dosyanızda hizmeti BIND_REMOTEVIEWS izniyle beyan ederek yapabilirsiniz. Bu işlem, diğer uygulamaların widget verilerinize serbest şekilde erişmesini engeller.

Örneğin, bir alanı doldurmak için RemoteViewsService kullanan bir widget oluştururken koleksiyonu görünümündeyken, manifest girişi aşağıdaki gibi görünebilir:

<service android:name="MyWidgetService"
    android:permission="android.permission.BIND_REMOTEVIEWS" />

Bu örnekte android:name="MyWidgetService", RemoteViewsService alt sınıfınızı ifade eder.

Koleksiyon içeren widget'lar için düzen

Widget düzeni XML dosyanızın temel gereksinimi, koleksiyon görünümleri: ListView, GridView, StackView veya AdapterViewFlipper. Şu öğe için widget_layout.xml dosyası: StackWidget örnek:

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

Boş görünümlerin, boş görünümün boş durumu temsil ettiği koleksiyon görünümünün kardeşleri olması gerektiğini unutmayın.

Widget'ınızın tamamı için bir düzen dosyasına ek olarak, koleksiyondaki her öğenin düzenini tanımlayan başka bir düzen dosyası oluşturun (ör. bir kitap koleksiyonundaki her kitap için bir düzen). Tüm öğeler aynı düzeni kullandığından StackWidget örneğinde yalnızca bir öğe düzeni dosyası (widget_item.xml) vardır.

Koleksiyonları olan widget'lar için AppWidgetProvider sınıfı

Normal widget'larda olduğu gibi, AppWidgetProvider alt sınıfınızdaki kodun büyük kısmı genellikle onUpdate() içine yerleştirilir. Bir sorgu oluştururken onUpdate() uygulamanızdaki temel fark bir diğer şey ise setRemoteAdapter() Bu, koleksiyon görünümüne verilerinin nereden alınacağını söyler. Ardından RemoteViewsService, RemoteViewsFactory uygulamanızı döndürebilir ve widget uygun verileri sunabilir. Google Takvim widget'ını Bu yöntemi çağırırken, şu yaklaşımı uygulamanıza işaret eden bir amaç iletin: RemoteViewsService ve güncellenecek widget'ı belirten widget kimliği.

Örneğin, StackWidget örneğinin onUpdate() öğesini nasıl uyguladığı burada gösterilmektedir RemoteViewsService cihazını cihazın uzak adaptörü olarak ayarlamak için geri çağırma yöntemini widget koleksiyonu:

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

Verileri koruma

Bu sayfada açıklandığı gibi, RemoteViewsService alt sınıfı uzak koleksiyon görünümünü doldurmak için kullanılan RemoteViewsFactory.

Özellikle şu adımları uygulayın:

  1. RemoteViewsService alt sınıfı. RemoteViewsService, üzerinden verilen hizmet bir uzak adaptör RemoteViews isteyebilir.

  2. RemoteViewsService alt sınıfınıza şunu uygulayan bir sınıf ekleyin: RemoteViewsFactory arayüzü. RemoteViewsFactory, uzak koleksiyon görünümü (ör. ListView, GridView, StackView) ile bu görünümün temel verileri arasındaki adaptör arayüzüdür. Sizin uygulaması, her öğe için bir RemoteViews nesnesi oluşturmaktan öğesine sahip olmayabilir. Bu arayüz, Adapter etrafında ince bir sarmalayıcıdır.

Hizmetinizin tek bir örneğine veya içerdiği verilere güvenemezsiniz. ısrarcı olabilir. Statik olmadığı sürece RemoteViewsService öğenize veri depolamayın. Eğer widget'ınızın verilerinin kalmasını istiyorsanız en iyi yaklaşım bir Verileri bulunan ContentProvider devam eder. Örneğin, bir market widget'ı her market alışverişi listesi öğesinin durumunu kalıcı bir konumda saklamanız gerekir. Örneğin, SQL veritabanı.

RemoteViewsService uygulamasının birincil içeriği, aşağıdaki bölümde açıklanan RemoteViewsFactory'dur.

RemoteViewsFactory arayüzü

RemoteViewsFactory arayüzünü uygulayan özel sınıfınız şunları sağlar: verilerini içeren widget'ı tıklayın. Bunu yapmak için de widget öğesi XML düzen dosyanızı bir veri kaynağıyla birleştirir. Bu kaynak verileri, veritabanından basit bir diziye kadar her şey olabilir. StackWidget Örneğinde, veri kaynağı bir WidgetItems dizisidir. RemoteViewsFactory verileri uzak toplama görünümüne yapıştıracak bir adaptör görevi görür.

Projeniz için uygulamanız gereken en önemli iki yöntem, RemoteViewsFactory alt sınıf onCreate() ve getViewAt().

Sistem, fabrikanızı ilk kez oluştururken onCreate() işlevini çağırır. Veri kaynağınızla ilgili bağlantıları veya imleçleri buradan ayarlarsınız. Örneğin, StackWidget örneği, bir diziyi başlatmak için onCreate() politikasını kullanır. WidgetItem nesne. Widget'ınız etkin olduğunda sistem bunlara erişir dizideki dizin konumlarını kullanarak nesneleri görüntüler ve bu nesnelerin, emin olun.

İşte StackWidget örneğinden RemoteViewsFactory onCreate() yönteminin bölümlerini gösteren uygulama:

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 yöntemi getViewAt(), veri kümesinde belirtilen position konumundaki verilere karşılık gelen bir RemoteViews nesnesi döndürür. İşte StackWidget örneğin RemoteViewsFactory uygulamasından bir alıntı:

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

Tek tek öğelere davranış ekleyin

Önceki bölümlerde, verilerinizin widget koleksiyonunuza nasıl bağlanacağı gösterilmiştir. Ama hesabınızdaki her öğeye ayrı ayrı dinamik davranış eklemek isterseniz, koleksiyon görünümünde mi?

Etkinlikleri onUpdate() ile yönetme sınıfını temsil edenler için setOnClickPendingIntent() kullanarak bir nesnenin tıklama davranışını (ör. bir düğmenin Activity başlatılmasına neden olur. Ancak tek bir koleksiyon öğesindeki alt görünümler için bu yaklaşıma izin verilmez. Örneğin, genel düğme ayarlamak için setOnClickPendingIntent() kullanabilirsiniz Gmail widget'ında görebilirsiniz (örneğin, liste öğelerinden yararlanabilirsiniz.

Bunun yerine, koleksiyondaki öğelere tek tek tıklama davranışı eklemek için setOnClickFillInIntent(). Bu işlem, koleksiyon görünümünüz için bekleyen bir intent şablonu oluşturmayı ve ardından RemoteViewsFactory aracılığıyla koleksiyondaki her öğe için bir doldurma intent'i ayarlamayı içerir.

Bu bölümde, tek tek öğelere nasıl davranış ekleneceği StackWidget örneği kullanılarak açıklanmaktadır. StackWidget örneğinde, kullanıcı üst görünüme dokunursa widget, "Dokunulan görünüm n" Toast mesajını gösterir. Burada n, dokunulan görünümün dizinidir (konumudur). İşleyişi:

  • AppWidgetProvider alt sınıfı olan StackWidgetProvider, TOAST_ACTION adlı özel bir işlemle bekleyen bir intent oluşturur.

  • Kullanıcı bir görünüme dokunduğunda, amaç etkinleşir ve içerik yayınlanır TOAST_ACTION

  • Bu yayın, StackWidgetProvider sınıfındakiler tarafından kesiliyor onReceive() yöntemini kullanıyorsanız ve widget'ta Toast mesajı görüntüleniyor dokunun. Koleksiyon öğeleriyle ilgili veriler, RemoteViewsFactory tarafından RemoteViewsService üzerinden sağlanır.

Beklemedeki intent şablonunu ayarlama

StackWidgetProvider (an AppWidgetProvider alt sınıf) beklemedeki niyet oluşturur. Bir koleksiyondaki öğeler tek tek ayarlayamaz kendi bekleyen intent'leriniz var. Bunun yerine, toplama bir bütün olarak beklemede bir şablondan yararlanırsınız. Her bir öğe, benzersiz bir tasarım oluşturmak için ve öğe bazında değerlendirebiliriz.

Bu sınıf ayrıca, kullanıcı bir görünüm. Bu etkinliği onReceive() yönteminde işler. Amaç işlem TOAST_ACTION. Widget, geçerli ayar için Toast mesajı gösterir görünüm.

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

Doldurma amacını ayarlayın

RemoteViewsFactory, koleksiyondaki her öğe için bir doldurma amacı belirlemelidir. Bu, tıklama işlemindeki bağımsız işlemlerin ayırt edilmesini mümkün kılar hakkında genel bilgi verir. Ardından, öğeye dokunulduğunda yürütülecek nihai amacı belirlemek için doldurma amacı PendingIntent şablonuyla birleştirilir.

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

Koleksiyon verilerini güncel tutun

Şekil 2, koleksiyon kullanan bir widget'taki güncelleme akışını göstermektedir. Bu sonuçta ve widget kodunun RemoteViewsFactory ile nasıl etkileşime girdiğini ve widget'ın tetikleyici güncellemeleri:

Şekil 2. Güncellemeler sırasında RemoteViewsFactory ile etkileşim.

Koleksiyon kullanan widget'lar kullanıcılara güncel içerikler sunabilir. Örneğin, Gmail widget'ı kullanıcılara gelen kutularının anlık görüntüsünü sunar. Bunu yapmak için: almak ve toplamak için RemoteViewsFactory ve koleksiyon görünümünüzü tetikleyin yeni verileri görüntüler.

Bunun için notifyAppWidgetViewDataChanged()'i aramak üzere AppWidgetManager simgesini kullanın. Bu çağrı, yeni verileri getirmenize olanak tanıyan RemoteViewsFactory nesnenizin onDataSetChanged() yöntemine geri çağrı gönderir.

Yoğun işlem gerektiren işlemleri onDataSetChanged() geri çağırma işlevinde senkronize olarak gerçekleştirebilirsiniz. Bu görüşmenin tamamlanacağı garanti edilir Meta veriler veya görünüm verileri RemoteViewsFactory'den getirilmeden önce. getViewAt() yönteminde yoğun işlem gerektiren işlemleri de gerçekleştirebilirsiniz. Bu çağrı uzun sürerse yükleme görünümü; RemoteViewsFactory nesnesi getLoadingView() yöntem - koleksiyon görünümünün karşılık gelen konumunda görüntülenir geri gelene kadar devam eder.

Bir koleksiyonu doğrudan göndermek için RemoteCollectionItems'ı kullanma

Android 12 (API düzeyi 31), setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items) özelliğini ekler. yöntemidir. Bu yöntem, uygulamanızın bir veri kümesi doldururken doğrudan koleksiyon görünümüne gidin. Adaptörünüzü bu yöntemi kullanarak ayarlarsanız bir RemoteViewsFactory uygulayın ve notifyAppWidgetViewDataChanged().

Bu yaklaşım, adaptörünüzü doldurmayı kolaylaştırmanın yanı sıra kullanıcılar yeni bir öğe görmek için listede aşağı kaydırdığında yeni öğelerin doldurulmasıyla ilgili gecikmeyi de ortadan kaldırır. Bağdaştırıcının bu şekilde ayarlanması için, yalnızca koleksiyon öğeleri grubunuz nispeten küçüktür. Ancak, örneğin, koleksiyonunuzda setImageViewBitmap'a iletilen çok sayıda Bitmaps varsa bu yaklaşım iyi çalışmaz.

Koleksiyonda sabit bir düzen grubu kullanılmıyorsa (yani bazı öğeler yalnızca bazen mevcutsa) koleksiyonun içerebileceği maksimum benzersiz düzen sayısını belirtmek için setViewTypeCount parametresini kullanın. Bu sayede, bağdaştırıcının uygulama widget'ınızdaki güncellemelerde yeniden kullanılması sağlanır.

Basitleştirilmiş RemoteViews koleksiyonlarının nasıl uygulanacağına dair bir örnek aşağıda verilmiştir.

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