Widget'ınızı geliştirin

Bu sayfada, Android 12'den (API düzeyi 31) itibaren sunulan isteğe bağlı widget geliştirmeleriyle ilgili ayrıntılar yer almaktadır. Bu özellikler isteğe bağlı olsa da kullanıcılarınızın widget deneyimini kolayca uygulayıp iyileştirebilir.

Dinamik renkler kullan

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 renkler elde etmenin iki yolu vardır:

Tema, kök düzeninde ayarlandıktan sonra, dinamik renkleri almak için kök veya alt öğelerin herhangi birinde yaygın renk özelliklerini kullanabilirsiniz.

Kullanabileceğiniz renk özelliklerine bazı örnekler:

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

Material 3 temasının kullanıldığı aşağıdaki örnekte cihazın tema rengi "mor". 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ındaki widget&#39;lar
Şekil 2. Widget koyu temada.

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

Dinamik renkler yalnızca Android 12 veya sonraki sürümleri çalıştıran cihazlarda kullanılabilir. Daha düşük sürümler için özel bir tema sağlamak isterseniz özel renklerinizle bir varsayılan tema ve varsayılan tema özelliklerini kullanarak yeni bir niteleyici (values-v31) oluşturun.

Aşağıda, Material 3 temasının kullanıldığı 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>

Ses desteğini etkinleştir

Uygulama İşlemleri, Google Asistan'ın ilgili kullanıcının sesli komutlarına yanıt olarak widget'ları göstermesine olanak tanır. Widget'ınızı yerleşik amaçlara (BII'ler) yanıt verecek şekilde yapılandırdığınızda, uygulamanız Android ve Android Auto gibi Asistan yüzeylerinde widget'ları proaktif olarak gösterebilir. Kullanıcıların, Asistan tarafından görüntülenen widget'ları başlatıcılarına sabitleme seçeneği bulunmaktadır. Bu şekilde etkileşimde bulunmalarını teşvik edebilirsiniz.

Ö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. Asistan, kullanıcılar bu BII'yi tetiklediğinde "Ok Google, bu hafta exampleApp'te kaç mil koşmuşum?" gibi isteklerde bulunarak widget'ınızı proaktif olarak gösterir.

Çeşitli kullanıcı etkileşimi kategorilerini kapsayan düzinelerce BBI vardır. Bunlar, neredeyse tüm Android uygulamalarının ses widget'larını geliştirmesine olanak tanır. Başlamak için Uygulama İşlemleri'ni Android widget'larıyla entegre etme bölümüne bakın.

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

Android 12, dinamik widget önizlemeleri ve widget açıklamaları ekleyerek uygulamanızın widget seçici deneyimini iyileştirmenize olanak tanır.

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

Android 12'den itibaren widget seçicide görüntülenen widget önizlemesi ölçeklenebilir. Bunu, widget'ın varsayılan boyutuna ayarlanmış bir XML düzeni olarak sağlarsınız. Önceden widget önizlemesi statik bir çekilebilir kaynaktı. Bazı durumlarda önizlemelerin, widget'ların ana ekrana eklendiklerinde nasıl görüneceğini yanlış yansıtmasına yol açıyordu.

Ölçeklenebilir widget önizlemelerini uygulamak için bunun yerine bir XML düzeni sağlamak üzere appwidget-provider öğesinin previewLayout özelliğini kullanı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 cihazını kullanır. Doğru önizleme düzenleri oluşturma konusunda yol gösterici bilgi için bu sayfada aşağıdaki bölüme bakın.

Hem previewLayout hem de previewImage özelliklerini belirtmenizi öneririz. Böylece, kullanıcının cihazı previewLayout özelliğini desteklemiyorsa uygulamanız previewImage özelliğini kullanabilir. 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 appwidget-provider öğesinin previewLayout özelliğini kullanarak bir XML düzeni sağlayı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ı tamamlayarak gerçek widget düzenini doğrudan varsayılan değerlerle sağlayabilirsiniz:

  • TextView öğeleri için android:text="@string/my_widget_item_fake_1" ayarlanıyor.

  • ImageView bileşenleri için android:src="@drawable/my_widget_icon" gibi bir varsayılan veya yer tutucu resim ya da simge 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 sunabilmesidir.

ListView, GridView veya StackView içeren daha karmaşık önizlemelere yönelik önerilen yaklaşımlar için 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ız için açıklama ekleyin

Android 12'den itibaren, widget'ınızda gösterilecek widget seçicisi için 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 görmez.

Daha yumuşak geçişler sağlayın

Android 12'den itibaren başlatıcılar, kullanıcılar uygulamanızı bir 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:id/background öğesini Android'in önceki sürümlerinde bozulmadan kullanabilir, ancak yoksayılır.

RemoteView'ların çalışma zamanında istenen değişikliği kullan

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