Widget ana makinesi oluşturma

Android ana ekranı, Android destekli çoğu cihazda bulunur ve kullanıcının içeriğe hızlıca erişmesi için uygulama widget'ları (veya widget'lar) yerleştirmesine olanak tanır. Ana ekran değişimi oluşturuyorsanız veya veya başka bir uygulamaya konduktan sonra, kullanıcının widget'ları AppWidgetHost. Bu değil çoğu uygulamanın yapması gereken bir şeydir. Ancak kendi ana makinenizi oluşturuyorsanız web sitesinin içerik sahibinin dolaylı olarak kabul ettiği sözleşme yükümlülüklerini anlamak önemlidir.

Bu sayfada, özel bir özelleştirmenin uygulanmasıyla ilgili sorumluluklara AppWidgetHost AppWidgetHost öğesinin nasıl uygulanacağına dair belirli bir örnek için Android ana ekranının LauncherAppWidgetHost kaynak koduna bakın.

Özel AppWidgetHost uygulamayla ilgili temel sınıflara ve kavramlara genel bir bakış aşağıda verilmiştir:

• Uygulama widget'ı ana makinesi: AppWidgetHost, Kullanıcı arayüzlerine widget yerleştiren uygulamalar için AppWidget hizmeti. AppWidgetHost , barındırıcının kendi paketinde benzersiz bir kimliğe sahip olmalıdır. Bu kimlik, ana makinenin tüm kullanımlarında devam eder. Kimlik, genellikle atamanıza olanak tanır.

• Uygulama widget kimliği: Her widget örneğine her seferinde benzersiz bir kimlik atanır . Görüntüleyin bindAppWidgetIdIfAllowed() Daha ayrıntılı bilgi için bir sonraki Widget'ları bağlama bölümüne bakın. İlgili içeriği oluşturmak için kullanılan benzersiz kimliği elde eder. allocateAppWidgetId(). Bu kimlik, barındırıcıdan silinene kadar widget'ın kullanım süresi boyunca varlığını korur. Barındırıcıya özgü tüm durumlar (ör. widget'ın boyutu ve konumu) barındırma paketi tarafından devam ettirilmeli ve uygulama widget'ı kimliğiyle ilişkilendirilmelidir.

• Uygulama widget'ı ana makine görünümü: Çerçeve olarak AppWidgetHostView widget'ın gösterilmesi gerektiğinde sarmalanması gerekir. Widget, bir AppWidgetHostView ile ilişkilendirilir. ana bilgisayar.

  • Sistem varsayılan olarak bir AppWidgetHostView oluşturur ancak ana makine, AppWidgetHostView'yi genişleterek kendi AppWidgetHostView alt sınıfını oluşturabilir.
  • Android 12'den (API düzeyi 31) itibaren AppWidgetHostView, dinamik olarak aşırı yüklenmiş renkleri işlemek için setColorResources() ve resetColorResources() yöntemlerini kullanıma sunar. Bu yöntemlere renkleri eklemek yayın sahibinin sorumluluğundadır.

• Seçenekler paketi: AppWidgetHost, seçenekler paketini kullanarak ilgili kişiye AppWidgetProvider hakkında bilgi edinin (örneğin, boyut aralıklarının listesini ve widget'ı kilit ekranında veya ana ekranda bulunuyor. Bu bilgiler, AppWidgetProvider'nin widget'ın içeriğini ve görünümünü nasıl ve nerede gösterildiğine göre özelleştirmesine olanak tanır. Bir widget'ın paketini değiştirmek için updateAppWidgetOptions() ve updateAppWidgetSize() öğelerini kullanabilirsiniz. Bu yöntemlerin her ikisi de AppWidgetProvider için onAppWidgetOptionsChanged() geri çağırma işlevini tetikler.

Bağlama widget'ları

Kullanıcı bir ana makineye widget eklediğinde bağlama adı verilen bir işlem gerçekleşir. Bağlama, belirli bir uygulama widget'ı kimliğinin belirli bir ana makineyle ve belirli bir AppWidgetProvider ile ilişkilendirilmesini 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 süreci kullanmak için uygulamanızın, BIND_APPWIDGET iznini barındırıcının manifest dosyasında beyan etmesi gerekir:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Ancak bu sadece başlangıç. Çalışma zamanında, kullanıcının barındırıcıya widget eklemesine izin vermek için uygulamanıza açıkça izin vermesi gerekir. Uygulamanızın widget ekleme iznine sahip olup olmadığını test etmek için bindAppWidgetIdIfAllowed() yöntemini kullanın. bindAppWidgetIdIfAllowed(), false sonucu döndürürse uygulamanız bir kullanıcıdan izin vermesini isteyen iletişim kutusu: "izin ver" (geçerli widget için) ekleme veya "her zaman izin ver" dahil edeceğiz.

Bu snippet, iletişim kutusunun nasıl gösterileceğine dair bir örnek sunar:

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)

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

Ana makine, kullanıcının eklediği widget'ın yapılandırılmaya ihtiyacı olup olmadığını kontrol etmelidir. Daha fazla bilgi için Kullanıcıların uygulama widget'larını yapılandırmasını etkinleştirme başlıklı makaleyi inceleyin.

Ev sahibi olma sorumlulukları

AppWidgetProviderInfo meta verilerini kullanarak widget'lar için çeşitli yapılandırma ayarları belirtebilirsiniz. Daha ayrıntılı olarak açıklanan bu yapılandırma seçeneklerini şu sayfada bulabilirsiniz: aşağıdaki bölümlerden AppWidgetProviderInfo Bir widget sağlayıcıyla ilişkilendirilmiş nesne.

Hedeflediğiniz Android sürümü ne olursa olsun, tüm ana makinelerde aşağıdaki sorumluluklardan yararlanabilirsiniz:

• Widget eklerken, widget kimliğini daha önce açıklandığı şekilde atayın. Bir widget ana makineden kaldırıldığında, widget kimliğinin ayrılmasını sağlamak için deleteAppWidgetId() işlevini çağırın.

• Widget eklerken, yapılandırmak istediğiniz yapılandırma kullanıma sunuldu. Genellikle, ana makinenin, widget'ın yapılandırma etkinliğini (varsa ve isteğe bağlı olarak işaretlenmediyse) hem configuration_optional hem de reconfigurable işaretlerini belirterek başlatması gerekir. Ayrıntılar için Widget'ı yapılandırma etkinliğinden güncelleme başlıklı makaleyi inceleyin. Bu, birçok widget'ın gösterilebilmesi için gerekli bir adımdır.

• Widget'lar, AppWidgetProviderInfo içinde varsayılan bir genişlik ve yükseklik belirtir meta verilerdir. Bu değerler hücrelerde tanımlanır ve targetCellWidth ve targetCellHeight geçerliyse Android 12 belirtilir (veya yalnızca minWidth ve minHeight belirtilirse 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 şeklinde düzenler. Bu senaryoda, ana makine varsayılan olarak minWidth ve minHeight kısıtlamalarını karşılayan minimum sayıda hücre kullanarak bir widget ekler.

Belirli platform sürümleri, önceki bölümde listelenen şartlara ek olarak barındırıcıya yeni sorumluluklar yükleyen özellikler sunar.

Hedeflenen Android sürümüne göre yaklaşımınızı belirleme

Android 12

Android 12 (API seviyesi 31), seçenekler paketinde bir widget örneğinin alabileceği olası boyutların listesini dpi cinsinden içeren ek bir List<SizeF> paketler. Sağlanan boyutların sayısı, ana makine uygulamasına bağlıdır. Düzenleyenler genelde Telefonlar için iki boyut (dikey ve yatay) ve dört boyutlu katlanabilir cihazlar da var.

Farklı öğe sayısı için MAX_INIT_VIEW_COUNT (16) sınır vardır AppWidgetProvider tarafından sağlanan RemoteViews RemoteViews. AppWidgetProvider nesneleri, RemoteViews nesnesini List<SizeF> içindeki her boyutla eşleştirdiğinden MAX_INIT_VIEW_COUNT boyuttan fazla sağlamaz.

Android 12, ayrıca maxResizeWidth ve maxResizeHeight özellikleri hakkında daha fazla bilgi edinin. Bu özelliklerden en az birini kullanan bir widget'ın özelliklerinin belirtilen boyutu aşmaması.

Ek kaynaklar

• Glance referans belgelerini inceleyin.