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 bir widget; düğmeler, arka planlar ve diğer bileşenler için cihaz tema 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 modlar için 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ındaki 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ın kullanıldığı bir örneği görebilirsiniz:

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

Ses desteğini etkinleştir

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ın antrenman özeti widget'ını, GET_EXERCISE_OBSERVATION BII'yi tetikleyen kullanıcının sesli komutlarını yerine getirecek şekilde 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ştirin

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 amacıyla, Android 15 ve sonraki sürümlerin yüklü olduğu cihazlarda oluşturulmuş bir widget önizlemesi, Android 12 ile Android 14 arası cihazlar için ölçeklendirilmiş bir widget önizlemesi (previewLayout belirterek) ve önceki sürümler için bir previewImage sağlayın.

Oluşturulan widget önizlemelerini widget seçiciye ekleme

Android 15 veya sonraki sürümlerin yüklü olduğu cihazlarda widget seçiciye RemoteViews sunabilmesi için uygulamaların build.gradle modülünde compileSdk değerini 35 veya üzeri olarak ayarlaması gerekir. Bu, uygulamaların seçicideki içeriği kullanıcının gördüğünü daha iyi temsil edecek şekilde güncelleyebileceği anlamına gelir.

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

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 bir 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'la 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 bir alanda görünen ancak XML düzeni nedeniyle 3x1 bir 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ümlerde widget seçicilerin 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ın, widget seçicide görüntülendiklerinde benzersiz bir adları 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 iyileştirilmiş geçişi etkinleştirmek için @android:id/background veya android.R.id.background kullanarak arka plan öğenizi tanımlayı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 bazıları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);