Basit bir widget oluşturma

Uygulama widget'ları, başka konumlara yerleştirebileceğiniz minyatür uygulama görünümleridir uygulamalarına (ana ekran gibi) ve düzenli güncellemeler alabilir. Bu görünümlerinde widget olarak adlandırılır ve Bir uygulama widget'ı sağlayıcı (veya widget sağlayıcı) ile bir tane. Şu özelliklere sahip bir uygulama bileşeni: ise diğer widget'ları muhafaza eder. Bu widget'lar, uygulama widget'ı ana makinesi (veya widget ana makinesi) olarak adlandırılır. 1. Şekil örnek bir müzik widget'ı gösterir:

Bu dokümanda, widget'ın bir widget sağlayıcısı kullanılarak nasıl yayınlanacağı açıklanmaktadır. Örneğin, AppWidgetHost oluşturma hakkında ayrıntılı bilgi Widget ana makinesi oluşturma başlıklı makaleye göz atın.

Widget'ınızı nasıl tasarlayacağınızla ilgili bilgi için Uygulama widget'larına genel bakış başlıklı makaleyi inceleyin.

Widget bileşenleri

Widget oluşturmak için aşağıdaki temel bileşenlere ihtiyacınız vardır:

AppWidgetProviderInfo nesne

Bir widget'ın meta verilerini (ör. widget'ın düzeni, güncelleme) açıklar sıklık ve AppWidgetProvider sınıfı. AppWidgetProviderInfo, XML'de şu şekilde tanımlanır: bahsetmek istiyorum.

AppWidgetProvider sınıf

Programlı arayüz öğeleri ile arayüz oluşturmanıza olanak tanıyan temel widget'ını tıklayın. Bu aracı kullanarak widget güncellendiğinde yayınları alırsınız, etkin, devre dışı veya silinmiş olabilir. AppWidgetProvider manifesto ve ardından uygulama bahsetmek istiyorum.

Düzeni görüntüle

Widget'ın ilk düzenini tanımlar. Düzen XML olarak değiştirin.

Şekil 2'de bu bileşenlerin genel uygulama widget'ı işleme sürecindeki yeri gösterilmektedir akışı sağlar.

Widget'ınız kullanıcı yapılandırması gerektiriyorsa uygulama widget'ı yapılandırmasını uygulayın etkinliği'ne dokunun. Bu etkinlik, kullanıcıların widget ayarlarını (örneğin, saat widget'ı için saat dilimi.

• Android 12'den (API düzeyi 31) itibaren, varsayılan bir ayar sağlayabilirsiniz Widget'ı yapılandırma ve kullanıcıların widget'ı daha sonra yeniden yapılandırmasına izin vermelidir. Bkz. widget'ın varsayılan yapılandırmasını ve Etkinleştir'i tıklayın. Kullanıcıların yerleştirilmiş widget'ları yeniden yapılandırmalarına olanak tanıyacak inceleyebilirsiniz.
• Android 11 (API düzeyi 30) veya önceki sürümlerde bu etkinlik her seferinde başlatılır Kullanıcı, widget'ı ana ekranına eklediğinde.

Ayrıca şu iyileştirmeleri de öneririz: esnek widget düzenleri, çeşitli geliştirmeler, gelişmiş widget'lar, koleksiyon widget'ları ve Widget oluşturma barındırma.

AppWidgetProviderInfo XML'i bildirme

AppWidgetProviderInfo nesnesi, bir widget'ın temel özelliklerini tanımlar. XML kaynak dosyasında AppWidgetProviderInfo nesnesini tanımlamak için tek bir <appwidget-provider> öğesini seçin ve projenin res/xml/ klasörüne kaydedin.

Bu, aşağıdaki örnekte gösterilmektedir:

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

Widget boyutlandırma özellikleri

Varsayılan ana ekran, widget'ları bir hücre ızgarasına göre kendi penceresinde konumlandırır tanımlanmış bir yüksekliği ve genişliği vardır. Çoğu ana ekran yalnızca widget'ların ızgara hücrelerinin tam sayı katları olan boyutlar (örneğin, iki hücre) üç hücre uzunluğunda ve dikey olarak olacak şekilde.

Widget boyutlandırma özellikleri, widget'ınız için varsayılan bir boyut belirtmenizi sağlar ve widget'ın boyutu için alt ve üst sınırları sağlar. Bu bağlamda, bir widget'ın varsayılan boyutu, widget'ın ilk açıldığında alacağı boyuttur ana ekrana eklendi.

Aşağıdaki tabloda, şunlarla ilgili <appwidget-provider> özellikleri açıklanmaktadır: widget boyutlandırmasına:

Örnek

Yukarıdaki tabloda yer alan özelliklerin widget boyutlandırmasını nasıl etkilediğini göstermek için aşağıdaki spesifikasyonları dikkate almanız gerekir:

• Bir ızgara hücresi 30 dp genişliğinde ve 50 dp yüksekliğindedir.
• Aşağıdaki özellik spesifikasyonu sağlanmıştır:

<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'den itibaren:

Varsayılan olarak targetCellWidth ve targetCellHeight özelliklerini kullan boyutu gösterilir.

Widget'ın boyutu varsayılan olarak 2x2'dir. Widget, 2x1 olacak şekilde yeniden boyutlandırılabilir veya en fazla 4x3 boyutunda olmalıdır.

Android 11 ve önceki sürümler:

Varsayılan boyutu hesaplamak için minWidth ve minHeight özelliklerini kullanın. widget'ı tıklayın.

Varsayılan genişlik = Math.ceil(80 / 30) = 3

Varsayılan yükseklik = Math.ceil(80 / 50) = 2

Widget'ın boyutu varsayılan olarak 3x2'dir. Widget, 2x1 olacak şekilde yeniden boyutlandırılabilir veya karar verebilirsiniz.

Ek widget özellikleri

Aşağıdaki tabloda, şunlarla ilgili <appwidget-provider> özellikleri açıklanmaktadır: özelleştirme dışındaki özellikleri de seçebilirsiniz.

Widget yayınlarını işlemek için AppWidgetProvider sınıfını kullanma

AppWidgetProvider sınıfı, widget yayınlarını yönetir ve widget'ı günceller yanıt verebilir. Aşağıdaki bölümlerde, bu risklerin manifest dosyasında AppWidgetProvider öğesini tanımlayıp uygulayın.

Manifest'te widget bildirme

Öncelikle, uygulamanızın AndroidManifest.xml sayfasında AppWidgetProvider sınıfını tanımlayın dosyasını seçin:

<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> öğesi, şunu belirten android:name özelliğini gerektirir: widget tarafından kullanılan AppWidgetProvider. Bileşen dışa aktarılmamalıdır AppWidgetProvider cihazınıza ayrı bir işlem anonsu yapılması gerekmiyorsa durum böyle değildir.

<intent-filter> öğesi,<action> android:name özelliği. Bu özellik, AppWidgetProvider şunu kabul eder: ACTION_APPWIDGET_UPDATE yayınla. Bu, açıkça belirtmeniz gereken tek yayındır. İlgili içeriği oluşturmak için kullanılan AppWidgetManager diğer tüm widget yayınlarını otomatik olarak AppWidgetProvider hizmetine şu şekilde gönderir: gerekir.

<meta-data> öğesi, AppWidgetProviderInfo kaynağını belirtir ve aşağıdaki özellikleri gerektirir:

• android:name: Meta veri adını belirtir. Tekliflerinizi otomatikleştirmek ve optimize etmek için android.appwidget.provider özelliğini kullanarak verileri AppWidgetProviderInfo tanımlayıcısı.
• android:resource: AppWidgetProviderInfo kaynağını belirtir konum.

AppWidgetProvider sınıfını uygulama

AppWidgetProvider sınıfının geçerliliği devam ediyor Şu rol olarak BroadcastReceiver: widget yayınlarını işlemeye yönelik kolaylık sınıfı. Yalnızca etkinliği alır örneğin güncellendiğinde, widget'la alakalı yayınlarda silindi, etkinleştirildi ve devre dışı bırakıldı. Bu yayın etkinlikleri gerçekleştiğinde aşağıdakiler AppWidgetProvider yöntemleri şu şekilde adlandırılır:

onUpdate()

Bu, widget'ın AppWidgetProviderInfo özelliğinde updatePeriodMillis özelliği var. Tabloyu inceleyin bu sayfada ek widget özelliklerini açıklayarak daha fazla bilgi edinin.

ziyaret edin.

Bu yöntem, kullanıcı widget'ı eklediğinde de çağrılır; böylece widget etkinlik işleyicileri tanımlamak gibi bazı temel kurulum Verilerin yükleneceği View nesne veya başlangıç işi widget'ta gösterilir. Ancak, configuration_optional işaretini kaldırınca bu yöntem, kullanıcı widget'ı ekler, ancak sonraki güncellemeler için çağrılanır. Uygulama, sırasında ilk güncellemeyi, başka bir web sitesi tarafından emin olun. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına izin verme başlıklı makaleye bakın.

ziyaret edin.

En önemli geri arama onUpdate(). Daha fazla bilgi için Etkinlikleri onUpdate() sınıfa giderek daha fazla bilgi edinebilirsiniz.

onAppWidgetOptionsChanged()

Bu işlev, widget ilk yerleştirildiğinde ve widget'ın ilk yeniden boyutlandırıldı. İçeriği widget'ın boyutuna göre göstermek veya gizlemek için bu geri çağırmayı kullanın. değerleridir. Boyut aralıklarını öğrenin ve Android 12'den itibaren öğesini çağırarak widget örneğinin alabileceği olası boyutların listesi getAppWidgetOptions() Bu, şunu içeren bir Bundle döndürür: takip etmek için:

• OPTION_APPWIDGET_MIN_WIDTH: bir widget örneğinin dp birimleri cinsinden genişliğinin alt sınırını içerir.
• OPTION_APPWIDGET_MIN_HEIGHT: değeri, bir widget örneğinin dp birimleri cinsinden yüksekliğinin alt sınırını içerir.
• OPTION_APPWIDGET_MAX_WIDTH: bir widget örneğinin dp birimleri cinsinden genişliğinin üst sınırını içerir.
• OPTION_APPWIDGET_MAX_HEIGHT: bir widget örneğinin dp birimleri cinsinden yüksekliğinin üst sınırını içerir.
• OPTION_APPWIDGET_SIZES: olası boyutların (List<SizeF>) listesini içerir. alabilir. Android 12'de kullanıma sunuldu.

onDeleted(Context, int[])

Bu, widget ana makinesinden bir widget her silindiğinde çağrılır.

onEnabled(Context)

Bu, widget'ın bir örneği ilk kez oluşturulduğunda çağrılır. Örneğin, kullanıcı widget'ınızın iki örneğini eklerse, bu yalnızca ilk kez. Yeni bir veritabanı açmanız veya tüm widget örnekleri için yalnızca bir kez gerçekleştirilmesi gerekiyorsa bu, yap.

onDisabled(Context)

Bu, widget'ınızın son örneği widget ana makinesi. onEnabled(Context) ürününde yaptığınız tüm çalışmaları burada temizlersiniz. Örneğin geçici bir veritabanını silebilirsiniz.

onReceive(Context, Intent)

Bu, her yayında ve önceki geri çağırmanın her birinden önce çağrılır yöntemlerine göz atın. Varsayılan olarak bu yöntemi uygulamanız gerekmez. AppWidgetProvider uygulaması, tüm widget yayınlarını filtreler ve yöntemlerine yer verin.

AppWidgetProvider sınıfı uygulamanızı yayın olarak beyan etmeniz gerekir alıcı, AndroidManifest içinde <receiver> öğesini kullanır. Bkz. widget'ını bu sayfadaki bölümünde bulabilirsiniz.

Etkinlikleri onUpdate() sınıfıyla yönetme

AppWidgetProvider için en önemli geri arama onUpdate(). Çünkü bu özellik: bir yapılandırma kullanmadığınız sürece, her widget bir ana makineye eklendiğinde configuration_optional işareti olmayan etkinlikler. Widget'ınız aşağıdakileri kabul ediyorsa Ardından, etkinlik işleyicilerini bu geri çağırmaya kaydedin. Eğer widget'ınız geçici dosyalar veya veritabanları oluşturmaz ya da başka işler yapmaz için geri çağırma yöntemi yoksa onUpdate(), tek geri çağırma yöntemi olabilir. tanımlamanız gerekir.

Örneğin, her açtığınızda etkinlik başlatan bir düğme aşağıdaki AppWidgetProvider uygulamasını kullanabilirsiniz:

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

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

Bu AppWidgetProvider yalnızca onUpdate() yöntemini tanımlar ve bunu lansmanını yapan bir PendingIntent bir Activity ve bunu widget'ın setOnClickPendingIntent(int, PendingIntent) kullanarak düğmesini tıklayın. Her girişte yineleyen bir döngü içerir. tarafından oluşturulan her bir widget'ı tanımlayan bir kimlik dizisi olan appWidgetIds isteyebilirsiniz. Kullanıcı widget'ın birden fazla örneğini oluşturursa hepsi aynı anda güncellenir. Ancak yalnızca bir updatePeriodMillis programı widget'ın tüm örnekleri için yönetilir. Örneğin, güncelleme planı iki saatte bir olarak tanımlanır ve widget'ın ikinci bir örneği eklenir bir saat sonra güncellenir ve her ikisi de ilk ve ikinci güncelleme dönemi yoksayılır. İkisi de 2 dakikada bir güncellenir saatlere denk geliyor.

Bkz. ExampleAppWidgetProvider.java örnek sınıfını inceleyin.

Widget yayın amaçları al

AppWidgetProvider, kolaylık sınıfıdır. Widget'ı almak istiyorsanız kendi BroadcastReceiver listenizi uygulayabilir veya geçersiz kılma işlemlerini yapabilirsiniz. "the" onReceive(Context,Intent) geri arama. Dikkate almanız gereken amaçlar ise takip etmek için:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Widget düzenini oluşturma

XML'de widget'ınız için bir başlangıç düzeni tanımlamanız ve projenin res/layout/ dizinini oluşturur. Tasarım yönergelerine bakın.

Bu araç hakkında bilginiz varsa widget düzeni kolayca oluşturabilirsiniz: düzenler. Ancak widget'ın düzen RemoteViews temel alınarak oluşturulur. her tür düzeni veya görünüm widget'ını desteklemeyen bir API'dir. Özel kampanyaları RemoteViews tarafından desteklenen görünümlerin veya alt sınıflarının sayısı.

RemoteViews ayrıca ViewStub değerini de destekler, Bu, düzeni lazily şişirmek için kullanabileceğiniz görünmez, sıfır boyutlu bir View kaynak kullanımını kolaylaştırır.

Durum bilgili davranış desteği

Android 12, aşağıdakileri kullanarak durum bilgili davranış için destek ekler: mevcut bileşenlerden yararlanın:

• CheckBox

• Switch

• RadioButton

Widget hâlâ durum bilgisizdir. Uygulamanız durumu depolamalı ve durum değişikliği etkinlikleri’ni tıklayın.

Aşağıdaki kod örneğinde bu bileşenlerin nasıl uygulanacağı gösterilmektedir.

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

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

İki düzen sağlayın: Android 12 çalıştıran cihazları hedefleyen bir düzen veya res/layout-v31 döneminde daha yüksek ve önceki diğer hedeflemelerde Varsayılan res/layout klasöründe Android 11 veya önceki sürümler.

Yuvarlatılmış köşeler uygulayın

Android 12, Widget'ınızın yuvarlatılmış köşelerinin yarıçapları:

• system_app_widget_background_radius: widget arka planının köşe yarıçapı (hiçbir zaman 28 dp.

• system_app_widget_inner_radius: köşe yarıçapını belirler. Bu tam olarak 8 dp 8 dp kullanırken güzel bir şekilde hizalamak için arka plan yarıçapından daha küçük dolgu.

Aşağıdaki örnekte Widget'ın köşesi için system_app_widget_background_radius ve Widget'ın içindeki görünümler için system_app_widget_inner_radius.

1 Widget'ın köşesi.

2 Widget'taki görünümün köşesi.

Yuvarlak köşeler ile ilgili önemli noktalar

• Üçüncü taraf başlatıcılar ve cihaz üreticileri system_app_widget_background_radius parametresini 28 dp'den küçük olması gerekir. system_app_widget_inner_radius parametresi her zaman şundan 8 dp küçüktür: system_app_widget_background_radius değerine ayarlanır.
• Widget'ınız @android:id/background kullanmıyorsa veya bir arka plan tanımlamıyorsa ana hatlarına göre kesen içerikler üretiyor. android:clipToOutline true değerine ayarlanırsa başlatıcı otomatik olarak arka planı tanımlar ve köşeleri 16 dp'ye kadar yuvarlanmış bir dikdörtgen kullanarak widget'ı kırpar. Daha fazla bilgi için Widget'ınızın Android 12.

Android'in önceki sürümleriyle widget uyumluluğu için özel özellikler tanımlamak ve bunları geçersiz kılmak için Aşağıdaki örnek XML dosyalarında gösterildiği gibi: Android 12:

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />