Android destekli çoğu cihazda bulunan Android ana ekranı, kullanıcının içeriğe hızlı erişim için uygulama widget'larını (veya widget'ları) yerleştirmesine olanak tanır. Ana ekran değişimi veya benzer bir uygulama oluşturuyorsanız AppWidgetHost
uygulayarak kullanıcının widget'ları yerleştirmesine de izin verebilirsiniz. Bu, çoğu uygulamanın yapması gereken bir şey değildir. Ancak kendi ana makinenizi oluşturuyorsanız barındırıcının sözleşmeden doğan yükümlülüklerini doğrudan kabul etmesi önemlidir.
Bu sayfada, özel AppWidgetHost
uygulamasının uygulanmasıyla ilgili sorumluluklara odaklanılmaktadır. AppWidgetHost
öğesinin nasıl uygulanacağına dair belirli bir örnek için Android ana ekranının LauncherAppWidgetHost
kaynak koduna bakın.
Aşağıda, özel bir AppWidgetHost
kullanımıyla ilgili temel sınıflar ve kavramlara genel bir bakış verilmiştir:
Uygulama widget'ı ana makinesi:
AppWidgetHost
, kullanıcı arayüzüne widget yerleştiren uygulamalar için AppWidget hizmetiyle etkileşimi sağlar.AppWidgetHost
, ana makinenin kendi paketinde benzersiz bir kimliğe sahip olmalıdır. Bu kimlik, ana makinenin tüm kullanımlarında kalıcı olur. Kimlik, genellikle uygulamanızda atadığınız sabit kodlu bir değerdir.Uygulama widget kimliği: Her widget örneğine bağlama sırasında benzersiz bir kimlik atanır.
bindAppWidgetIdIfAllowed()
konusuna ve daha ayrıntılı bilgi için aşağıdaki Widget'ları bağlama bölümüne bakın. Ana makine, benzersiz kimliğiallocateAppWidgetId()
kullanarak alır. Bu kimlik, ana makineden silinene kadar widget'ın ömrü boyunca kalır. Widget'ın boyutu ve konumu gibi ana makineye özgü durumlar, barındırma paketi tarafından korunmalı ve uygulama widget'ı kimliğiyle ilişkilendirilmelidir.Uygulama widget'ı ana makine görünümü:
AppWidgetHostView
'ı, gösterilmesi gerektiğinde widget'ın içine alındığı bir çerçeve olarak düşünebilirsiniz. Bir widget, ana makine tarafından her şişirildiğindeAppWidgetHostView
ile ilişkilendirilir.- Varsayılan olarak, sistem bir
AppWidgetHostView
oluşturur ancak ana makine bu özelliği genişleterek kendiAppWidgetHostView
alt sınıfını oluşturabilir. AppWidgetHostView
, Android 12'den (API düzeyi 31) başlayarak dinamik olarak aşırı yüklenen renklerin işlenmesi içinsetColorResources()
veresetColorResources()
yöntemlerini kullanıma sundu. Bu yöntemlere renklerin sağlanmasından sunucu sorumludur.
- Varsayılan olarak, sistem bir
Seçenekler paketi:
AppWidgetHost
,AppWidgetProvider
'e widget'ın nasıl gösterileceği (ör. boyut aralıkları listesi) ve widget'ın kilit ekranında mı yoksa ana ekranda mı bulunduğuyla ilgili bilgileri iletmek için seçenekler paketini kullanır. Bu bilgiler sayesindeAppWidgetProvider
, widget'ın içeriğini ve görünümünü nasıl ve nerede görüntülendiğine bağlı olarak uyarlayabilir. Widget paketini değiştirmek içinupdateAppWidgetOptions()
veupdateAppWidgetSize()
tuşlarını kullanabilirsiniz. Bu yöntemlerin her ikisi deAppWidgetProvider
içinonAppWidgetOptionsChanged()
geri çağırmasını tetikler.
Widget'ları bağlama
Kullanıcı, ana makineye bir widget eklediğinde bağlama adı verilen bir işlem gerçekleşir. Bağlama, belirli bir uygulamanın widget kimliğini belirli bir ana makine ve belirli bir AppWidgetProvider
ile ilişkilendirmeyi ifade eder.
Bağlama API'leri, ana makinenin bağlama için özel bir kullanıcı arayüzü sağlamasına da olanak tanır. Bu işlemi kullanmak için uygulamanızın ana makinenin manifest dosyasında BIND_APPWIDGET
iznini beyan etmesi gerekir:
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
Ancak bu sadece başlangıç. Çalışma zamanında, kullanıcı uygulamanızın ana makineye bir widget eklemesine izin vermek için uygulamanıza açıkça izin vermelidir. Uygulamanızın widget'ı ekleme izni olup olmadığını test etmek için bindAppWidgetIdIfAllowed()
yöntemini kullanın. bindAppWidgetIdIfAllowed()
işlevi false
değerini döndürürse uygulamanız, kullanıcıdan izin vermesini isteyen bir iletişim kutusu görüntülemelidir: mevcut widget eklemesi için "izin ver" veya gelecekteki tüm widget eklemelerini kapsaması için "her zaman izin ver".
Bu snippet, iletişim kutusunun nasıl gösterileceğine dair bir örnek sunar:
Kotlin
val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply { putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName) // This is the options bundle described in the preceding section. putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options) } startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Java
Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName); // This is the options bundle described in the preceding section. intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options); startActivityForResult(intent, REQUEST_BIND_APPWIDGET);
Barındırıcı, bir kullanıcının eklediği widget'ın yapılandırılmasına ihtiyaç olup olmadığını kontrol etmelidir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına izin verme konusuna bakın.
Ev sahibi olma sorumlulukları
AppWidgetProviderInfo
meta verilerini kullanarak widget'lar için çeşitli yapılandırma ayarları belirtebilirsiniz.
Aşağıdaki bölümlerde daha ayrıntılı olarak açıklanan bu yapılandırma seçeneklerini, bir widget sağlayıcıyla ilişkilendirilmiş AppWidgetProviderInfo
nesnesinden alabilirsiniz.
Hedeflediğiniz Android sürümüne bakılmaksızın, tüm ana makineler aşağıdaki sorumluluklara sahiptir:
Widget eklerken, widget kimliğini daha önce açıklandığı şekilde atayın. Bir widget ana makineden kaldırıldığında widget kimliğini ayırmak için
deleteAppWidgetId()
çağrısı yapın.Widget eklerken, yapılandırma etkinliğinin başlatılmasının gerekip gerekmediğini kontrol edin. Genellikle, widget'ın yapılandırma etkinliğini (varsa ve hem
configuration_optional
hem dereconfigurable
işaretlerini belirterek isteğe bağlı olarak işaretlenmiyorsa) ana makinenin başlatması gerekir. Ayrıntılar için Widget'ı yapılandırma etkinliğinden güncelleme bölümüne bakın. Bu, birçok widget'ın gösterilebilmesi için gerekli bir adımdır.Widget'lar,
AppWidgetProviderInfo
meta verilerinde varsayılan bir genişlik ve yükseklik belirtir. Bu değerler,targetCellWidth
vetargetCellHeight
belirtilmişse Android 12'den başlayarak hücrelerde veya yalnızcaminWidth
veminHeight
belirtilmişse dps olarak tanımlanır. Widget boyutlandırma özellikleri bölümüne bakın.Widget'ın en az bu kadar dps ile yerleştirildiğinden emin olun. Örneğin, birçok ana makine, simgeleri ve widget'ları bir ızgarada hizalar. Bu senaryoda ana makine, varsayılan olarak
minWidth
veminHeight
kısıtlamalarına uyan minimum hücre sayısını kullanarak bir widget ekler.
Önceki bölümde listelenen gereksinimlere ek olarak, belirli platform sürümleri, ana makineye yeni sorumluluklar veren özellikler sunar.
Hedeflenen Android sürümüne göre yaklaşımınızı belirleyin
Android 12
Android 12 (API düzeyi 31), bir widget örneğinin seçenekler paketinde alabileceği olası boyutların listesini dps cinsinden içeren ekstra bir List<SizeF>
içerir.
Sağlanan boyutların sayısı, ana makine uygulamasına bağlıdır. Ana makineler genellikle telefonlar için iki boyut (dikey ve yatay) ve katlanabilir cihazlar için dört boyut sağlar.
AppWidgetProvider
öğesinin RemoteViews
ile sağlayabileceği farklı RemoteViews
sayısı MAX_INIT_VIEW_COUNT
(16) ile sınırlıdır.
AppWidgetProvider
nesneleri, bir RemoteViews
nesnesini List<SizeF>
içindeki her boyutla eşlediğinden en fazla MAX_INIT_VIEW_COUNT
boyut sağlayın.
Android 12'de dps'de maxResizeWidth
ve maxResizeHeight
özellikleri de kullanıma sunuluyor. Bu özelliklerden en az birini kullanan bir widget'ın, özellikler tarafından belirtilen boyutu aşmamasını öneririz.
Ek kaynaklar
Glance
referans belgelerini inceleyin.