Widget'ınızı geliştirin

Bu sayfada, Android 12'den (API düzeyi 31) itibaren kullanılabilen isteğe bağlı widget geliştirmeleriyle ilgili ayrıntılar yer almaktadır. Bu özellikler isteğe bağlıdır ancak kullanıcılarınızın widget deneyimini iyileştirmek ve uygulamak için kolayca kullanılabilir.

Dinamik renkler kullanın

Android 12'den itibaren widget'lar, düğmeler, arka planlar ve diğer bileşenler için cihaz teması renklerini kullanabilir. Bu sayede, farklı widget'lar arasında daha sorunsuz geçişler ve tutarlılık sağlanır.

Dinamik renkleri iki şekilde elde edebilirsiniz:

Tema, kök düzeninde ayarlandıktan sonra dinamik renkleri almak için kökteki veya alt öğelerinden herhangi birindeki ortak renk özelliklerini kullanabilirsiniz.

Kullanabileceğiniz renk özelliklerine örnek olarak şunlar verilebilir:

  • ?attr/primary
  • ?attr/primaryContainer
  • ?attr/onPrimary
  • ?attr/onPrimaryContainer

Material 3 temasının kullanıldığı aşağıdaki örnekte cihazın tema rengi "mor"dur. Vurgu rengi ve widget arka planı, şekil 1 ve 2'de gösterildiği gibi açık ve koyu modlara uyarlanır.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>
Açık mod temasında widget
Şekil 1. Açık temadaki widget.
Koyu mod temasında widget&#39;lar
Şekil 2. Koyu temalı widget.

Dinamik renkler için geriye dönük uyumluluk

Dinamik renkler yalnızca Android 12 veya sonraki sürümlerin yüklü olduğu cihazlarda kullanılabilir. Alt sürümler için özel bir tema sağlamak istiyorsanız özel renklerinizle varsayılan bir tema oluşturun ve varsayılan tema özelliklerini kullanarak yeni bir niteliklendirici (values-v31) ekleyin.

Aşağıda, Material 3 temasını kullanan bir örnek verilmiştir:

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

Sesli desteği etkinleştirme

Uygulama İşlemleri, Google Asistan'ın alakalı kullanıcı sesli komutlarına yanıt olarak widget'lar göstermesine olanak tanır. Widget'ınızı yerleşik intent'lere (BIIs) yanıt verecek şekilde yapılandırarak uygulamanız, Android ve Android Auto gibi Asistan platformlarında widget'ları proaktif olarak gösterebilir. Kullanıcılar, Asistan'ın gösterdiği widget'ları başlatıcılarına sabitleyebilir. Bu sayede kullanıcıların Asistan'la etkileşimi artar.

Örneğin, egzersiz uygulamanız için egzersiz özeti widget'ını, GET_EXERCISE_OBSERVATION BII'yi tetikleyen kullanıcı sesli komutlarını yerine getirmek üzere yapılandırabilirsiniz. Kullanıcılar "Ok Google, bu hafta ÖrnekUygulama'da kaç kilometre koştum?" gibi istekler göndererek bu BII'yi tetiklediğinde Asistan, widget'ınızı proaktif olarak gösterir.

Çeşitli kullanıcı etkileşimi kategorilerini kapsayan düzinelerce BI vardır. Bu BI'lar, neredeyse tüm Android uygulamalarının widget'larını ses için geliştirmesine olanak tanır. Başlamak için Uygulama işlemlerini Android widget'larıyla entegre etme başlıklı makaleyi inceleyin.

Uygulamanızın widget seçici deneyimini iyileştirme

Android 12, ölçeklendirilmiş widget önizlemeleri ve widget açıklamaları eklemenize olanak tanır. Android 15, oluşturulan widget önizlemeleriyle uygulamanızın widget seçici deneyimini iyileştirmenize olanak tanır.

Uygulamanızın widget seçici deneyimini iyileştirmek için Android 15 ve sonraki sürümlerde oluşturulmuş bir widget önizlemesi, Android 12 ile Android 14 arasındaki sürümlerde ölçeklendirilmiş bir widget önizlemesi (previewLayout belirterek) ve önceki sürümlerde previewImage sağlayın.

Oluşturulan widget önizlemelerini widget seçiciye ekleme

Android 15 veya sonraki sürümlerin widget seçicisine RemoteViews sağlayabilmek için uygulamaların, build.gradle modülü dosyasında compileSdk değerini 35 veya sonraki bir sürüme ayarlaması gerekir. Bu sayede uygulamalar, seçicideki içeriği kullanıcının gördüğü içeriği daha iyi yansıtacak şekilde güncelleyebilir.

Uygulamalar, widget'larının görünümünü güncel ve kişiselleştirilmiş bilgilerle güncellemek için AppWidgetManager, setWidgetPreview ve getWidgetPreview yöntemlerini kullanabilir.

Jetpack Glance ile güncellenmiş önizleme oluşturma

Glance.compose tek bir kompozisyon çalıştırır. Bu nedenle, composable'ınızın gövdesinde askıya alma işlevleri, akışlar veya benzer asenkron çağrılar kullanılmaz. Bunun yerine sabit veriler kullanmanız gerekir.

Aşağıdaki örnekte, güncellenmiş bir önizleme oluşturmak için Jetpack Glance kullanılmaktadır. setWidgetPreview'ın bu snippet'te yöntem olarak gösterilmesi için compileSdk derleme ayarının 35 veya daha yeni bir sürüm olması gerekir.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

Jetpack Glance olmadan güncellenmiş önizleme oluşturma

RemoteViews'ü Glance olmadan kullanabilirsiniz. Aşağıdaki örnekte, bir XML widget düzeni kaynağı yüklenir ve önizleme olarak ayarlanır. setWidgetPreview'ün bu snippet'te bir yöntem olarak gösterilmesi için 35 veya daha yeni bir compileSdk derleme ayarı gerekir.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

Widget seçiciye ölçeklenebilir widget önizlemeleri ekleme

Android 12'den itibaren widget seçicide gösterilen widget önizlemesi ölçeklenebilir. Widget'ın varsayılan boyutuna ayarlanmış bir XML düzeni olarak sağlarsınız. Daha önce widget önizlemesi statik bir çizilebilir kaynaktı. Bu durum, bazı durumlarda widget'ların ana ekrana eklendiğinde nasıl göründüğünü yanlış yansıtan önizlemelere yol açıyordu.

Ölçeklenebilir widget önizlemelerini uygulamak için appwidget-provider öğesinin previewLayout özelliğini kullanarak XML düzeni sağlayın:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

Gerçek widget ile aynı düzeni, gerçekçi varsayılan veya test değerleriyle kullanmanızı öneririz. Çoğu uygulama aynı previewLayout ve initialLayout değerlerini kullanır. Doğru önizleme düzenleri oluşturma hakkında bilgi edinmek için bu sayfanın aşağıdaki bölümüne bakın.

Kullanıcının cihazı previewLayout'yi desteklemiyorsa uygulamanızın previewImage'yi kullanabilmesi için hem previewLayout hem de previewImage özelliklerini belirtmenizi öneririz. previewLayout özelliği, previewImage özelliğine göre önceliklidir.

Doğru önizlemeler oluşturmak için önerilen yaklaşımlar

Ölçeklenebilir widget önizlemelerini uygulamak için XML düzeni sağlamak üzere appwidget-provider öğesinin previewLayout özelliğini kullanın:

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Widget önizlemesini gösteren resim
Şekil 3. Varsayılan olarak 3x3 alanda görünen ancak XML düzeni nedeniyle 3x1 alana sığabilen bir widget önizlemesi.

Doğru bir önizleme görüntülemek için aşağıdaki adımları uygulayarak doğrudan gerçek widget düzenini varsayılan değerlerle sağlayabilirsiniz:

  • TextView öğeleri için android:text="@string/my_widget_item_fake_1" ayarlama

  • ImageView bileşenleri için varsayılan veya yer tutucu resim ya da simge (ör. android:src="@drawable/my_widget_icon") ayarlama

Varsayılan değerler olmadan önizlemede yanlış veya boş değerler gösterilebilir. Bu yaklaşımın önemli bir avantajı, yerelleştirilmiş önizleme içeriği sağlayabilmenizdir.

ListView, GridView veya StackView içeren daha karmaşık önizlemeler için önerilen yaklaşımlar hakkında ayrıntılı bilgi edinmek üzere Dinamik öğeler içeren doğru önizlemeler oluşturma başlıklı makaleyi inceleyin.

Ölçeklenebilir widget önizlemeleriyle geriye dönük uyumluluk

Android 11 (API düzeyi 30) veya önceki sürümlerdeki widget seçicilerinin widget'ınızın önizlemelerini göstermesine izin vermek için previewImage özelliğini belirtin.

Widget'ın görünümünü değiştirirseniz önizleme resmini güncelleyin.

Widget'ınıza ad ekleme

Widget'lar, widget seçicide gösterilirken benzersiz bir ada sahip olmalıdır.

Widget adları, AndroidManifest.xml dosyasındaki widget'ın receiver öğesinin label özelliğinden yüklenir.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Widget'ınız için açıklama ekleme

Android 12'den itibaren, widget seçicinin widget'ınız için göstereceği bir açıklama girin.

Bir widget&#39;ı ve açıklamasını gösteren widget seçiciyi gösteren resim
Şekil 4. Bir widget'ı ve açıklamasını gösteren örnek widget seçici.

&lt;appwidget-provider&gt; öğesinin description özelliğini kullanarak widget'ınız için bir açıklama girin:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

descriptionRes özelliğini Android'in önceki sürümlerinde kullanabilirsiniz ancak widget seçici bu özelliği yoksayar.

Daha akıcı geçişler yapma

Android 12'den itibaren başlatıcılar, kullanıcılar uygulamanızı widget'tan başlattığında daha sorunsuz bir geçiş sağlar.

Bu gelişmiş geçişi etkinleştirmek için arka plan öğenizi tanımlamak üzere @android:id/background veya android.R.id.background kullanın:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

Uygulamanız, Android'in önceki sürümlerinde @android:id/background'ü sorunsuz bir şekilde kullanabilir ancak bu işlev yoksayılır.

RemoteViews'ın çalışma zamanındaki değişikliğini kullanma

Android 12'den itibaren, RemoteViews özelliklerinin çalışma zamanında değiştirilmesini sağlayan çeşitli RemoteViews yöntemlerinden yararlanabilirsiniz. Eklenen yöntemlerin tam listesi için RemoteViews API referansına bakın.

Aşağıdaki kod örneğinde bu yöntemlerden birkaçının nasıl kullanılacağı gösterilmektedir.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);