Android destekli cihazların çoğunda bulunan Android ana ekranı, kullanıcıların içeriğe hızlı erişim için uygulama widget'larını (veya widget'ları) yerleştirmesine olanak tanır. Ana ekran yerine yeni bir uygulama veya benzer bir uygulama oluşturuyorsanız AppWidgetHost
öğesini uygulayarak kullanıcının widget'ları yerleştirmesine de izin verebilirsiniz. Çoğu uygulamanın böyle bir işlem yapması gerekmez ancak kendi ana makinenizi oluşturuyorsanız ana makinenin dolaylı olarak kabul ettiği sözleşme yükümlülüklerini anlamanız önemlidir.
Bu sayfada, özel AppWidgetHost
uygulanmasıyla ilgili sorumluluklara odaklanılmaktadır. AppWidgetHost
öğesinin nasıl uygulanacağına dair belirli bir örnek için Android ana ekranının kaynak koduna
LauncherAppWidgetHost
bakın.
Aşağıda, özel bir AppWidgetHost
uygulanmasıyla ilgili önemli sınıflar ve kavramlarla ilgili genel bir bakış sunulmaktadır:
Uygulama widget ana makinesi:
AppWidgetHost
, kullanıcı arayüzüne widget yerleştiren uygulamalar için AppWidget hizmetiyle etkileşim sağlar.AppWidgetHost
, ana makinenin kendi paketi içinde benzersiz bir kimliğe sahip olmalıdır. Bu kimlik, ana makinenin tüm kullanımlarında kalır. Kimlik, genellikle uygulamanızda atadığınız sabit kodlu bir değerdir.Uygulama widget kimliği: Bağlama sırasında her widget örneğine benzersiz bir kimlik atanır.
bindAppWidgetIdIfAllowed()
ve daha fazla bilgi için aşağıdaki Bağlama widget'ları bölümüne bakın. Ana makine, benzersiz kimliğiallocateAppWidgetId()
kullanarak elde eder. Bu kimlik ana makineden silinene kadar widget'ın kullanım ömrü boyunca kalır. Widget'ın boyutu ve konumu gibi ana makineye özel tüm durumlar, barındırma paketi tarafından korunmalı ve uygulama widget kimliğiyle ilişkilendirilmelidir.Uygulama widget'ı ana makine görünümü:
AppWidgetHostView
'i, görüntülenmesi gerektiğinde widget'ın içine yerleştirildiği bir çerçeve olarak düşünebilirsiniz. Widget, ana makine tarafından her genişletildiğinde birAppWidgetHostView
ile ilişkilendirilir.- Varsayılan olarak, sistem bir
AppWidgetHostView
oluşturur ancak ana makine bunu genişleterek kendiAppWidgetHostView
alt sınıfını oluşturabilir. AppWidgetHostView
, Android 12'den (API düzeyi 31) itibaren dinamik olarak aşırı yüklenen renkleri işlemek içinsetColorResources()
veresetColorResources()
yöntemlerini kullanıma sunuyor. Ev sahibi, bu yöntemlere renk eklemekten sorumludur.
- Varsayılan olarak, sistem bir
Seçenekler paketi:
AppWidgetHost
, widget'ın görüntülenme şekli (örneğin, boyut aralıkları listesi) ve widget'ın kilit ekranında mı yoksa ana ekranda mı olduğuyla ilgili bilgileriAppWidgetProvider
'e iletmek için seçenek paketini kullanır. Bu bilgiler,AppWidgetProvider
tarafından widget'ın nasıl ve nerede görüntülendiğine göre widget'ın içeriğini ve görünümünü özelleştirmesini sağlar. Bir widget'ın paketini değiştirmek içinupdateAppWidgetOptions()
veupdateAppWidgetSize()
seçeneklerini kullanabilirsiniz. Bu yöntemlerin her ikisi deAppWidgetProvider
öğesine geri çağırmayı (onAppWidgetOptionsChanged()
) tetikler.
Widget bağlama
Bir kullanıcı ana makineye bir widget eklediğinde, bağlama adı verilen bir işlem gerçekleşir. Bağlama, belirli bir uygulama widget'ı kimliğinin belirli bir ana makine ve belirli bir AppWidgetProvider
ile ilişkilendirilmesi anlamına gelir.
Bağlama API'leri, bir ana makinenin bağlama için özel bir kullanıcı arayüzü sağlamasına da imkan tanır. Bu süreci 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 daha başlangıç. Çalışma zamanında kullanıcı, uygulamanıza ana makineye widget eklemesine izin vermek için 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: geçerli widget ekleme için "izin ver" veya gelecekteki tüm widget eklemelerini kapsamak için "her zaman izin ver".
Bu snippet'te, iletişim kutusunun nasıl gösterileceğine dair bir örnek verilmiştir:
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);
Düzenleyen, kullanıcının eklediği widget'ın yapılandırılmasına gerek olup olmadığını kontrol etmelidir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasına izin verme bölümüne bakın.
Toplantı sahibinin 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 ele alınan bu yapılandırma seçeneklerini, bir widget sağlayıcıyla ilişkilendirilmiş AppWidgetProviderInfo
nesnesinden alabilirsiniz.
Hedeflediğiniz Android sürümünden bağımsız olarak tüm ana makineler aşağıdaki sorumluluklara sahiptir:
Widget eklerken, widget kimliğini daha önce açıklandığı gibi ayırın. Bir widget ana makineden kaldırıldığında, widget kimliğinin yerini belirlemek 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 varsa ve isteğe bağlı olarak işaretlenmemişse hem
configuration_optional
hem dereconfigurable
işaretlerini belirterek ana makinenin, yapılandırma etkinliğini 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örüntülenebilmesi için gerekli bir adımdır.Widget'lar,
AppWidgetProviderInfo
meta verilerinde varsayılan bir genişlik ve yükseklik belirtir. Bu değerler hücrelerde tanımlanır (targetCellWidth
vetargetCellHeight
belirtilmişse Android 12'den başlayarak) veya yalnızcaminWidth
veminHeight
belirtilmişse dps. 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 ızgara üzerinde hizalar. Bu senaryoda ana makine, varsayılan olarak
minWidth
veminHeight
kısıtlamalarını karşılayan minimum hücre sayısını kullanarak bir widget ekler.
Önceki bölümde belirtilen gereksinimlere ek olarak, belirli platform sürümleri ana makineye yeni sorumluluklar atayan ö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 ek bir List<SizeF>
içerir.
Sağlanan boyutların sayısı ana makine uygulamasına bağlıdır. Ana makineler telefonlar için genellikle iki boyut (dikey ve yatay) ve katlanabilir cihazlar için dört boyut sunar.
AppWidgetProvider
öğesinin RemoteViews
'e sağlayabileceği farklı RemoteViews
sayısı için MAX_INIT_VIEW_COUNT
(16) sınırı vardı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, dps biçiminde maxResizeWidth
ve maxResizeHeight
özelliklerini de kullanıma sunuyor. Bu özelliklerden en az birini kullanan bir widget'ın, özellikler tarafından belirtilen boyutu aşmamasını öneririz.
Ek kaynaklar
Glance
referans belgelerini inceleyin.