Esnek widget düzenleri sağlama

Bu sayfada widget boyutlandırması ve daha fazla esneklik için yapılan ayrıntılandırmalar açıklanmaktadır. kullanıma sunuldu. Ayrıca, widget'ınız için nasıl boyut belirleyeceğiniz de ayrıntılı olarak açıklanmaktadır.

Widget boyutları ve düzenleri için iyileştirilmiş API'leri kullanma

Android 12 (API düzeyi 31) sürümünden itibaren, aşağıdaki bölümlerde açıklandığı gibi aşağıdakileri yaparak daha hassas boyut özellikleri ve esnek düzenler sağlayabilirsiniz:

  1. Ek widget boyutlandırma kısıtlamaları belirleme

  2. Duyarlı düzenler veya tam düzenler sağlama

Android'in önceki sürümlerinde OPTION_APPWIDGET_MIN_WIDTH, OPTION_APPWIDGET_MIN_HEIGHT, OPTION_APPWIDGET_MAX_WIDTH ve OPTION_APPWIDGET_MAX_HEIGHT ekstralarını kullanarak widget'ın boyut aralıklarını elde etmek ve ardından widget'ın boyutunu tahmin etmek mümkündür ancak bu mantık her durumda işe yaramaz. Android 12 veya sonraki sürümleri hedefleyen widget'lar için duyarlı veya tam düzenler.

Ek widget boyutlandırma kısıtlamaları belirtme

Android 12, widget'ınızın farklı ekran boyutlarına sahip farklı cihazlarda daha güvenilir şekilde ölçeklendirilmesini sağlayan API'ler ekler.

Mevcut minWidth'e ek olarak minHeight, minResizeWidth ve minResizeHeight özellikleri için aşağıdaki yeni appwidget-provider özelliklerini kullanın:

  • targetCellWidth ve targetCellHeight: widget'ın hedef boyutunu başlatıcı ızgara hücreleri açısından tanımlar. Eğer bu özellikler minWidth veya minHeight yerine kullanılır.

  • maxResizeWidth ve maxResizeHeight: Başlatıcının, kullanıcının widget'ı yeniden boyutlandırmasına izin verdiği maksimum boyutu tanımlar.

Aşağıdaki XML'de, boyutlandırma özelliklerinin nasıl kullanılacağı gösterilmektedir.

<appwidget-provider
  ...
  android:targetCellWidth="3"
  android:targetCellHeight="2"
  android:maxResizeWidth="250dp"
  android:maxResizeHeight="110dp">
</appwidget-provider>

Duyarlı düzenler sağlama

Düzenin widget'ın boyutuna bağlı olarak değişmesi gerekiyorsa her biri farklı boyutlar için geçerli olan küçük bir düzen grubu oluşturmak. Bu mümkün değildir, bir diğer seçenek de tam widget'a göre düzenler sağlamaktır. boyutunu bu sayfada bulabilirsiniz.

Bu özellik, widget'ı her farklı boyutta gösterdiğinde sistemin uygulamayı uyandırması gerekmediğinden daha sorunsuz ölçeklendirme ve genel olarak daha iyi sistem sağlığı sağlar.

Aşağıdaki kod örneğinde, bir düzen listesinin nasıl sağlanacağı gösterilmektedir.

Kotlin

override fun onUpdate(...) {
    val smallView = ...
    val tallView = ...
    val wideView = ...

    val viewMapping: Map<SizeF, RemoteViews> = mapOf(
            SizeF(150f, 100f) to smallView,
            SizeF(150f, 200f) to tallView,
            SizeF(215f, 100f) to wideView
    )
    val remoteViews = RemoteViews(viewMapping)

    appWidgetManager.updateAppWidget(id, remoteViews)
}

Java

@Override
public void onUpdate(...) {
    RemoteViews smallView = ...;
    RemoteViews tallView = ...;
    RemoteViews wideView = ...;

    Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
    viewMapping.put(new SizeF(150f, 100f), smallView);
    viewMapping.put(new SizeF(150f, 200f), tallView);
    viewMapping.put(new SizeF(215f, 100f), wideView);
    RemoteViews remoteViews = new RemoteViews(viewMapping);

    appWidgetManager.updateAppWidget(id, remoteViews);
}

Widget'ın aşağıdaki özelliklere sahip olduğunu varsayalım:

<appwidget-provider
    android:minResizeWidth="160dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="200dp">
</appwidget-provider>

Önceki kod snippet'i şu anlama gelir:

  • smallView, 160 dp (minResizeWidth) × 110 dp boyutundan itibaren destekler (minResizeHeight) ila 160 dp × 199 dp (sonraki son sipariş noktası - 1 dp).
  • tallView, 160 dp × 200 dp ile 214 dp arası değerleri destekler (sonraki son sipariş noktası - 1) × 200dp.

  • wideView, 215 dp × 110 dp (minResizeHeight) ila 250 dp (maxResizeWidth) × 200 dp (maxResizeHeight) boyutlarını destekler.

Widget'ınız minResizeWidth × minResizeHeight ile maxResizeWidth × maxResizeHeight arasındaki boyut aralığını desteklemelidir. Bu aralıkta düzenler arasında geçiş yapmak için kesim noktasına karar verebilirsiniz.

Duyarlı düzen örneği
Şekil 1. Duyarlı düzen örneği.

Doğru düzenler sağlayın

Küçük bir duyarlı düzen grubu uygun değilse bunun yerine widget'ın gösterildiği boyutlara göre uyarlanmış farklı düzenler. Bu genellikle telefonlar için iki boyut (dikey ve yatay mod) ve katlanabilir cihazlar için dört boyuttur.

Uygulamanızın bu çözümü uygulamak için aşağıdaki adımları gerçekleştirmesi gerekir:

  1. Boyut grubu değiştiğinde çağrılan aşırı yükleme AppWidgetProvider.onAppWidgetOptionsChanged().

  2. Boyutları içeren bir Bundle döndüren AppWidgetManager.getAppWidgetOptions() işlevini çağırın.

  3. AppWidgetManager.OPTION_APPWIDGET_SIZES anahtarına Bundle içinden erişin.

Aşağıdaki kod örneğinde, tam düzenlerin nasıl sağlanacağı gösterilmektedir.

Kotlin

override fun onAppWidgetOptionsChanged(
        context: Context,
        appWidgetManager: AppWidgetManager,
        id: Int,
        newOptions: Bundle?
) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, id, newOptions)
    // Get the new sizes.
    val sizes = newOptions?.getParcelableArrayList<SizeF>(
            AppWidgetManager.OPTION_APPWIDGET_SIZES
    )
    // Check that the list of sizes is provided by the launcher.
    if (sizes.isNullOrEmpty()) {
        return
    }
    // Map the sizes to the RemoteViews that you want.
    val remoteViews = RemoteViews(sizes.associateWith(::createRemoteViews))
    appWidgetManager.updateAppWidget(id, remoteViews)
}

// Create the RemoteViews for the given size.
private fun createRemoteViews(size: SizeF): RemoteViews { }

Java

@Override
public void onAppWidgetOptionsChanged(
    Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newOptions) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, appWidgetId, newOptions);
    // Get the new sizes.
    ArrayList<SizeF> sizes =
        newOptions.getParcelableArrayList(AppWidgetManager.OPTION_APPWIDGET_SIZES);
    // Check that the list of sizes is provided by the launcher.
    if (sizes == null || sizes.isEmpty()) {
      return;
    }
    // Map the sizes to the RemoteViews that you want.
    Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
    for (SizeF size : sizes) {
        viewMapping.put(size, createRemoteViews(size));
    }
    RemoteViews remoteViews = new RemoteViews(viewMapping);
    appWidgetManager.updateAppWidget(id, remoteViews);
}

// Create the RemoteViews for the given size.
private RemoteViews createRemoteViews(SizeF size) { }

Widget'ınız için boyut belirleme

Her widget, Android 12 veya sonraki sürümleri çalıştıran cihazlar için bir targetCellWidth ve targetCellHeight (veya Android'in tüm sürümleri için minWidth ve minHeight) tanımlamalıdır. Bu değerler, widget'ın varsayılan olarak kapladığı minimum alanı belirtir. Ancak kullanıcılar ana ekranlarına bir widget eklediklerinde, belirttiğiniz minimum genişlik ve yükseklikten daha fazla yer kaplar.

Android ana ekranları, kullanıcılara widget ve simge yerleştirebilecekleri kullanılabilir alanlar ızgaraları sunar. Bu çizelge cihaza göre değişebilir. örneğin birçok Cep telefonları 5x4, tabletler ise daha büyük bir ızgara sunabilir. Widget'ınız eklenir, asgari sayıda hücreyi işgal edecek şekilde uzatılır, kısıtlarını karşılamak için gereklidir. Çalışan cihazlarda targetCellWidth ve targetCellHeight Android 12 veya sonraki sürümler ya da minWidth ve minHeight kısıtlamaları Android 11 (API düzeyi 30) veya önceki sürümleri çalıştıran cihazlar.

Bir hücrenin hem genişliği hem de yüksekliği ve widget'lara uygulanan otomatik kenar boşluklarının boyutu cihazlara göre değişiklik gösterebilir. İstediğiniz dolu hücre sayısına bağlı olarak, widget'ınızın tipik bir 5x4 ızgaralı cep telefonundaki minimum boyutlarını kabaca tahmin etmek için aşağıdaki tabloyu kullanın:

Hücre sayısı (genişlik x yükseklik) Dikey modda kullanılabilir boyut (dp) Yatay modda kullanılabilir boyut (dp)
1x1 57x102 dp 127x51dp
2x1 130x102 dp 269x51dp
3x1 203x102 dp 412x51dp
4x1 276x102dp 554x51dp
5x1 349x102dp 697x51dp
5x2 349x220 dp 697x117dp
5x3 349x337 dp 697x184dp
5x4 349x455dp 697x250dp
... ... ...
n x m (73n - 16) x (118m - 16) (142n - 15) x (66m - 15)

Sağladığınız değerleri belirtmek için dikey mod hücre boyutlarını kullanın minWidth, minResizeWidth ve maxResizeWidth özellikleri. Benzer şekilde, minHeight, minResizeHeight ve maxResizeHeight özellikleri için sağladığınız değerleri bilgilendirmek üzere yatay mod hücre boyutlarını kullanın.

Bunun nedeni, dikey modda hücre genişliğinin genellikle daha küçük olmasıdır. bir ayar vardır. Benzer şekilde, hücre yüksekliği genellikle yatay moddayken dikey moda göre daha küçüktür.

Örneğin, widget'ınızın genişliğinin Google Pixel 4'te bir hücreye kadar ölçeklendirilebilir olmasını istiyorsanız minResizeWidth özelliğinin değerinin 57 dp'den küçük olmasını sağlamak için minResizeWidth özelliğini en fazla 56 dp olarak ayarlamanız gerekir. Bunun nedeni, bir hücrenin dikey olarak en az 57 dp genişliğinde olmasıdır. Benzer şekilde, widget'ınızın yüksekliğinin aynı cihazdaki bir hücrede yeniden boyutlandırılabilir olmasını istiyorsanız minResizeHeight özelliğinin değerinin 51 dp'den küçük olduğundan emin olmak için minResizeHeight özelliğini en fazla 50 dp'ye ayarlamanız gerekir. Çünkü yatay modda bir hücre en az 51 dp yüksekliğindedir.

Her widget, 2022'den itibaren şu boyutlarda yeniden boyutlandırılabilir. minResizeWidth/minResizeHeight ve maxResizeWidth/maxResizeHeight özellikleridir. Bu nedenle, aralarında herhangi bir boyut aralığına uyum sağlaması gerekir.

Örneğin, yerleşimde widget'ın varsayılan boyutunu ayarlamak için şu özellikleri ayarlayın:

<appwidget-provider
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>

Bu, widget'ın varsayılan boyutunun targetCellWidth ve targetCellHeight özellikleri veya 180×110 dp, çalışan cihazlar için minWidth ve minHeight tarafından belirtildi Android 11 veya önceki sürümler. İkinci durumda, hücrelerdeki boyut cihaza göre değişiklik gösterebilir.

Ayrıca, widget'ınızın desteklenen boyut aralıklarını ayarlamak için aşağıdakileri ayarlayabilirsiniz: özellikler:

<appwidget-provider
    android:minResizeWidth="180dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="530dp"
    android:maxResizeHeight="450dp">
</appwidget-provider>

Önceki özelliklerde belirtildiği gibi, widget'ın genişliği 180 dp ile 530 dp arasında, yüksekliği ise 110 dp ile 450 dp arasında değiştirilebilir. Ardından, aşağıdaki koşullar sağlandığı sürece widget'ın boyutu 3x2'den 5x2'ye kadar değiştirilebilir:

  • Cihazda 5x4 ekran görüntüsü var.
  • Hücre sayısı ile dps cinsinden kullanılabilir boyut arasındaki eşleme, bu sayfadaki minimum boyut tahminini gösteren tabloyu takip eder.
  • Widget bu boyut aralığına uyum sağlar.

Kotlin

val smallView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_small)
val mediumView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_medium)
val largeView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_large)

val viewMapping: Map<SizeF, RemoteViews> = mapOf(
        SizeF(180f, 110f) to smallView,
        SizeF(270f, 110f) to mediumView,
        SizeF(270f, 280f) to largeView
)

appWidgetManager.updateAppWidget(appWidgetId, RemoteViews(viewMapping))

Java

RemoteViews smallView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_small);
RemoteViews mediumView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_medium);
RemoteViews largeView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_large);

Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
viewMapping.put(new SizeF(180f, 110f), smallView);
viewMapping.put(new SizeF(270f, 110f), mediumView);
viewMapping.put(new SizeF(270f, 280f), largeView);
RemoteViews remoteViews = new RemoteViews(viewMapping);

appWidgetManager.updateAppWidget(id, remoteViews);

Widget'ın önceki bölümde tanımlanan duyarlı düzenleri kullandığını varsayın kullanabilirsiniz. Bu, R.layout.widget_weather_forecast_small olarak belirtilen düzenin 180dp (minResizeWidth) x 110dp (minResizeHeight) ile 269x279dp (sonraki kesme noktaları - 1) arasında kullanılacağı anlamına gelir. Benzer şekilde, R.layout.widget_weather_forecast_medium 270x110 dp ile 270x279 dp arasında, R.layout.widget_weather_forecast_large ise 270x280 dp ile 530 dp (maxResizeWidth) x 450 dp (maxResizeHeight) arasında kullanılır.

Kullanıcı widget'ı yeniden boyutlandırdıkça görünümü, aşağıdaki örneklerde gösterildiği gibi hücrelerdeki her boyuta uyacak şekilde değişir.

En küçük 3x2 ızgara boyutunda hava durumu widget&#39;ı örneği. Kullanıcı arayüzünde konum adı (Tokyo), sıcaklık (14°) ve parçalı bulutlu hava durumunu gösteren simge gösterilir.
Şekil 2. 3x2 R.layout.widget_weather_forecast_small.

4x2 &quot;orta&quot; boyutta hava durumu widget&#39;ı seçin. Widget&#39;ı yeniden boyutlandırma Bu şekilde önceki widget boyutundaki kullanıcı arayüzünün tamamını oluşturabilirsiniz. ve &#39;Çoğunlukla bulutlu&#39; etiketini ekler sıcaklıkla ilgili bir tahmin 16:00 - 19:00 arası.
Şekil 3. 4x2 R.layout.widget_weather_forecast_medium.

5x2 &quot;orta&quot; boyutta hava durumu widget&#39;ı seçin. Widget&#39;ı bu şekilde yeniden boyutlandırdığınızda, önceki boyutla aynı kullanıcı arayüzü elde edilir. Bunun tek farkı, daha fazla yatay alan kaplaması için bir hücre uzunluğu kadar uzatılmış olmasıdır.
Şekil 4. 5x2 R.layout.widget_weather_forecast_medium.

5x3 &quot;büyük&quot; boyutta örnek hava durumu widget&#39;ı seçin. Widget&#39;ı bu şekilde yeniden boyutlandırdığınızda, önceki widget boyutlarındaki tüm kullanıcı arayüzü öğeleri korunur ve widget&#39;ın içine Salı ve Çarşamba günleri için hava durumu tahminini içeren bir görünüm eklenir. Güneşli veya yağmurlu havayı gösteren semboller günlük en yüksek ve en düşük sıcaklıkları görebilirsiniz.
Şekil 5. 5x3 R.layout.widget_weather_forecast_large.

5x4 &quot;büyük&quot; boyutlu örnek hava durumu widget&#39;ı. Widget&#39;ı bu şekilde yeniden boyutlandırdığınızda önceki widget boyutlarındaki tüm kullanıcı arayüzü öğeleri korunur ve Perşembe ile Cuma günleri (ve her günün hava durumunu, en yüksek ve en düşük sıcaklığını gösteren ilgili sembolleri) eklenir.
Şekil 6. 5x4 R.layout.widget_weather_forecast_large.