Widget'ınızı geliştirin

Bu sayfada, Android 12'den (API düzeyi 31) itibaren kullanıma sunulan 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 kolayca uygulayıp iyileştirebilir.

Dinamik renkler kullan

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

Dinamik renkleri elde etmenin iki yolu vardır:

• Kök düzeninde sistemin varsayılan temasını (@android:style/Theme.DeviceDefault.DayNight) kullanın.

• Android sürüm 1.6.0'dan başlayarak Android için Materyal Bileşenler kitaplığından Material 3 temasını (Theme.Material3.DynamicColors.DayNight) kullanın.

Tema kök düzende ayarlandıktan sonra, dinamik renkleri almak için kök veya alt öğelerindeki ortak renk özelliklerini kullanabilirsiniz.

Kullanabileceğiniz renk özelliklerine ilişkin bazı örnekleri aşağıda bulabilirsiniz:

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

Malzeme 3 temasının kullanıldığı aşağıdaki örnekte cihazın tema rengi "morum"dur. Vurgu rengi ve widget arka planı, Şekil 1 ve 2'de gösterildiği gibi açık ve koyu modlara uyum sağlar.

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

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. Alt sürümler için özel bir tema sağlamak üzere, özel renklerinizle varsayılan bir tema ve varsayılan tema özelliklerini kullanarak yeni bir niteleyici (values-v31) oluşturun.

Burada, Malzeme 3 temasının kullanıldığı bir örnek verilmiştir:

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

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

<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ı sesli komutlarına yanıt olarak widget'ları görüntülemesini sağlar. Widget'ınızı yerleşik amaçlara (BII'lar) 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, Asistan tarafından görüntülenen widget'ları Başlatıcıya sabitleyerek gelecekteki etkileşimi teşvik edebilirler.

Örneğin, egzersiz uygulamanız için antrenman özeti widget'ını GET_EXERCISE_OBSERVATION BII'yi tetikleyen kullanıcı sesli komutlarını gerçekleştirecek şekilde yapılandırabilirsiniz. Asistan, kullanıcılar bu BII'yi tetiklediğinde widget'ınızı proaktif olarak görüntüler. Bunun için, "Ok Google, bu hafta ÖrnekUygulama'da kaç kilometre koştum?"

Çeşitli kullanıcı etkileşimi kategorilerini kapsayan düzinelerce BII vardır. Bunlar, neredeyse her Android uygulamasının ses widget'larını geliştirmesine olanak tanır. Başlamak için Uygulama İşlemleri'ni Android widget'larıyla entegre etme konusuna 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 ekleme

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

Ölçeklenebilir widget önizlemeleri uygulamak için bunun yerine XML düzeni sağlamak amacıyla appwidget-provider öğesinin previewLayout özelliğini kullanın:

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

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

Kullanıcının cihazı previewLayout özelliğini desteklemiyorsa uygulamanızın, previewImage kullanmaya devam edebilmesi 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 amacıyla appwidget-provider öğesinin previewLayout özelliğini kullanın:

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

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

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

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

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

ListView, GridView veya StackView içeren daha karmaşık önizlemelere yönelik önerilen yaklaşımlarla ilgili ayrıntılar için Dinamik öğeler içeren doğru önizlemeler oluşturma bölümüne bakın.

Ö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östermesini sağlamak 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ız için görüntülenmesi için widget seçici için bir açıklama sağlayın.

<appwidget-provider> öğ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 bu özellik widget seçici tarafından yoksayılır.

Daha yumuşak geçişler etkinleştirin

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

Bu iyileştirilmiş 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 bozulmadan @android:id/background kullanabilir ancak bu kod yoksayılır.

RemoteView'ların çalışma zamanı 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.

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

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