Widget'ınızı geliştirin

Yazma yöntemini deneyin
Jetpack Compose, Android için önerilen kullanıcı arayüzü araç setidir. Compose tarzı API'leri kullanarak widget oluşturmayı öğrenin.
Jetpack Glance →

Bu sayfada, Android 12 (API düzeyi 31) sürümünden 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 kolayca uygulanabilir ve kullanıcılarınızın widget deneyimini iyileştirir.

Dinamik renkleri kullanma

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üzende ayarlandıktan sonra dinamik renkleri almak için kökte veya alt öğelerinde ortak renk özelliklerini kullanabilirsiniz.

Kullanabileceğiniz renk özelliklerinden bazıları şunlardır:

  • ?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ı, 1. ve 2. şekillerde 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>
Açık mod temasındaki widget
1. Şekil. Açık temadaki widget.
Koyu mod temasındaki widget&#39;lar
Şekil 2. Koyu temadaki 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. Daha düşük sürümler için özel bir tema sağlamak üzere, özel renklerinizi ve varsayılan tema özelliklerini kullanarak yeni bir niteleyici (values-v31) içeren varsayılan bir tema oluşturun.

Material 3 temasının kullanıldığı bir örneği aşağıda bulabilirsiniz:

/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 amaçlara (BII) yanıt verecek şekilde yapılandırarak uygulamanızın, Android ve Android Auto gibi Asistan yüzeylerinde proaktif olarak widget göstermesini sağlayabilirsiniz. Kullanıcılar, Asistan tarafından gösterilen widget'ları başlatıcılarına sabitleyebilir ve böylece gelecekteki etkileşimleri teşvik edebilir.

Örneğin, egzersiz uygulamanız için egzersiz özeti widget'ını, GET_EXERCISE_OBSERVATION BII'yi tetikleyen kullanıcı sesli komutlarını karşılayacak şekilde yapılandırabilirsiniz. Asistan, kullanıcılar "Ok Google, bu hafta ExampleApp'te kaç kilometre koştum?" gibi isteklerde bulunarak bu BII'yi tetiklediğinde widget'ınızı proaktif olarak gösterir.

Çeşitli kullanıcı etkileşimi kategorilerini kapsayan onlarca BII vardır. Bu sayede neredeyse tüm Android uygulamaları, ses için widget'larını geliştirebilir. Başlamak için Uygulama İşlemlerini Android widget'larıyla entegre etme başlıklı makaleye bakın.

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ızdaki 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 cihazlarda ölçeklendirilmiş bir widget önizlemesi (previewLayout belirterek) ve önceki sürümlerde previewImage sağlayın.

Oluşturulan widget önizlemelerini widget seçiciye ekleme

Uygulamaların, Android 15 veya sonraki sürümlerdeki widget seçiciye RemoteViews sağlayabilmesi için modül build.gradle dosyasında compileSdk değerini 35 veya sonraki bir sürüm olarak ayarlaması gerekir. Bu sayede uygulamalar, seçicideki içeriği kullanıcının gördüklerini 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 bir kompozisyon çalıştırır. Bu nedenle, composable'ınızın gövdesinde askıya alma işlevleri, akışlar veya benzeri eşzamansız ç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. compileSdk'ın bu snippet'te yöntem olarak gösterilmesi için setWidgetPreview'ın 35 veya sonraki bir sürümünün yüklü 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 özelliğini Glance olmadan kullanabilirsiniz. Aşağıdaki örnekte bir XML widget düzen kaynağı yüklenir ve önizleme olarak ayarlanır. setWidgetPreview öğesinin bu snippet'te yöntem olarak gösterilmesi için 35 veya sonraki 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. Bu düzeni, 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 önizlemelerin, widget'lar ana ekrana eklendiğinde nasıl göründüğünü yanlış yansıtmasına neden oluyordu.

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

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

Gerçekçi varsayılan veya test değerleriyle, gerçek widget'la aynı düzeni kullanmanızı öneririz. Çoğu uygulama aynı previewLayout ve initialLayout değerlerini kullanır. Doğru önizleme düzenleri oluşturmayla ilgili rehberlik için bu sayfadaki aşağıdaki bölüme bakın.

Uygulamanızın, kullanıcının cihazı previewLayout özelliğini desteklemediğinde previewImage özelliğini 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 önizlemeleri uygulamak için previewLayout öğesinin appwidget-provider özelliğini kullanarak bir XML düzeni sağlayın:

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

Doğru bir önizleme göstermek 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 varsayılan veya yer tutucu bir 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 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ç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, widget seçicide gösterilirken benzersiz bir ada sahip olmalıdır.

Widget'ların 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'ınız için gösterilecek widget seçiciye bir açıklama ekleyin.

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

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

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

Android'in önceki sürümlerinde descriptionRes özelliğini kullanabilirsiniz ancak bu özellik, widget seçici tarafından yok sayılır.

Geçişleri daha akıcı hâle getirme

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 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 iznini sorunsuz bir şekilde kullanabilir ancak bu izin 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 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);