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.

Aşağıda, bir proje yönetimi yaklaşımının uygulanmasında yer alan temel sınıflar ve özel AppWidgetHost:

  • Uygulama widget'ı ana makinesi: AppWidgetHost, kullanıcı arayüzüne widget yerleştiren uygulamalar için AppWidget hizmetiyle etkileşim sağlar. AppWidgetHost , barındırıcının kendi paketinde benzersiz bir kimliğe sahip olmalıdır. Bu kimlik devam ediyor kullanımında yardımcı olur. Kimlik, genellikle atamanıza olanak tanır.

  • Uygulama widget kimliği: Her widget örneğine her seferinde benzersiz bir kimlik atanır . Daha fazla bilgi için bindAppWidgetIdIfAllowed() bölümüne ve aşağıdaki 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.

    • Varsayılan olarak sistem bir AppWidgetHostView oluşturur, ancak ana makine şunları yapabilir: kapsamını 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, widget'ın içeriğini ve görünümünü nasıl ve nasıl gösterildiği yeri seçin. Bir widget'ın paketini değiştirmek için updateAppWidgetOptions() ve updateAppWidgetSize() öğelerini kullanabilirsiniz. Bu yöntemlerin her ikisi de onAppWidgetOptionsChanged() AppWidgetProvider için geri arama.

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 makine ve belirli AppWidgetProvider.

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 izni varsa bindAppWidgetIdIfAllowed() yöntemidir. bindAppWidgetIdIfAllowed() false döndürürse uygulamanız, kullanıcıdan izin vermesini isteyen bir iletişim kutusu göstermelidir: Mevcut widget ekleme işlemi için "izin ver" veya gelecekteki tüm widget ekleme işlemlerini kapsayacak şekilde "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);

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.

Barındırıcının 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ünden bağımsız olarak tüm ana makinelerin aşağıdaki sorumlulukları vardır:

  • Widget eklerken widget kimliğini daha önce açıklandığı şekilde ayırı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ırma etkinliğinin başlatılması gerekip gerekmediğini kontrol edin. Genellikle ana makinenin widget yapılandırmasını başlatması gerekir etkinliği varsa ve isteğe bağlı olarak işaretlenmemişse configuration_optional ve reconfigurable işaretleri. 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, AppWidgetProviderInfometa verilerinde varsayılan bir genişlik ve yükseklik belirtir. Bu değerler, targetCellWidth ve targetCellHeight belirtilmişse Android 12'den itibaren hücrelerde veya yalnızca minWidth ve minHeight belirtilmişse dp olarak tanımlanır. Görüntüleyin Widget boyutlandırma özellikleri.

    Widget'ın en az bu sayıda dp ile düzenlendiğinden emin olun. Örneğin, Birçok ana makine, simgeleri ve widget'ları bir ızgarada hizalar. 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.

Önceki bölümde listelenen şartlara ek olarak, platform sürümleri, kullanıcılara yeni sorumluluklar veren özellikler ana bilgisayar.

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

Android 12

Android 12 (API düzeyi 31), bu listeyi içeren ek bir List<SizeF> içerir bir widget örneğinin seçenekler paketinde alabileceği dps cinsinden olası boyutlardadır. Sağlanan boyut sayısı, ana makine uygulamasına bağlıdır. Barındıranlar genellikle telefonlar için dikey ve yatay olmak üzere iki boyut, katlanabilir cihazlar için ise dört boyut sağlar.

Bir AppWidgetProvider'nin RemoteViews'a sağlayabileceği farklı RemoteViews sayısı MAX_INIT_VIEW_COUNT (16) ile sınırlıdır. AppWidgetProvider nesneleri, RemoteViews nesnesini List<SizeF> içindeki her boyutla eşleştirdiğinden MAX_INIT_VIEW_COUNT boyuttan fazla sağlamaz.

Android 12'de, dps cinsinden maxResizeWidth ve maxResizeHeight özellikleri de kullanıma sunulmuştur. Bu özelliklerden en az birini kullanan widget'ların, özellikler tarafından belirtilen boyutu aşmamasını öneririz.

Ek kaynaklar

  • Glance referans dokümanlarına bakın.