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 bu riskleri Widget'ınız için bir boyut belirleyin.

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 kullanılabilir.

Android'in önceki sürümlerinde, bir sanal makinenin boyut aralıklarını widget'ı kullanarak OPTION_APPWIDGET_MIN_WIDTH, OPTION_APPWIDGET_MIN_HEIGHT, OPTION_APPWIDGET_MAX_WIDTH, ve OPTION_APPWIDGET_MAX_HEIGHT ve widget'ın boyutunu tahmin ediyor. Ancak bu mantık, durumlardan birine sahip olmaları halinde başlatabilirler. Android 12 veya sonraki sürümleri hedefleyen widget'lar için duyarlı veya tam sayfa düzenler sağlamanızı öneririz.

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

Android 12, widget'ınızın sorunsuz bir şekilde çalışmasını sağlayan API'ler sunar. değişiklik gösteren ekran boyutlarına sahip farklı cihazlarda daha güvenilir şekilde boyutlandırılabilir.

Mevcut minWidth, minHeight, minResizeWidth ve minResizeHeight özelliklerine ek olarak 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ımlamalıdır. Tanımlanmışsa 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ımlayın.

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

Widget'ın boyutuna bağlı olarak düzenin değişmesi gerekiyorsa her biri belirli bir boyut aralığı için geçerli olan küçük bir düzen grubu oluşturmanızı öneririz. Bu mümkün değilse bu sayfada açıklandığı gibi çalışma zamanındaki tam widget boyutuna göre düzenler de sağlayabilirsiniz.

Bu özellik daha yumuşak ölçeklendirme ve genel olarak daha iyi sistem sağlar Çünkü sistemin her aramada uygulamayı uyandırması gerekmez widget farklı bir boyutta görüntülenir.

Aşağıdaki kod örneğinde, düzenlerin 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 (minResizeHeight) ile 160 dp × 199 dp (sonraki kesme noktası - 1 dp) arasında desteklenir.
• 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 biçimini destekler (maxResizeWidth) × 200dp (maxResizeHeight).

  Not: Widget'ın boyutu maxResizeWidth × maxResizeHeight. Widget boyutlandırma bölümüne bakın özellikleri hakkında daha fazla bilgi edinin.

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

Ş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 telefonlar için genellikle iki boyut (dikey ve yatay mod) ve katlanabilir cihazlar.

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

1. Aşırı yük AppWidgetProvider.onAppWidgetOptionsChanged(), Bu boyut, boyut kümesi değiştiğinde çağrılır.

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

3. Bundle'dan AppWidgetManager.OPTION_APPWIDGET_SIZES anahtarına erişin.

Not: Boyutların listesini sağlamak başlatıcının sorumluluğundadır. Öğe cihazda bu alanı desteklemeyen bir başlatıcı varsa, boş veya değersiz olabilir.

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 bir boyut belirleme

Her widget, cihazlar için bir targetCellWidth ve targetCellHeight tanımlamalıdır Android 12 veya sonraki sürümleri çalıştıran ya da minWidth ve minHeight kullanan herkes için Android sürümleri (Android'in kullandığı minimum alan miktarını gösterir) varsayılan olarak. 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 ızgara cihaza göre değişiklik gösterebilir. Örneğin, birçok cep telefonu 5x4 ızgara sunarken tabletler 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.

Hücrenin hem genişliği hem yüksekliği hem de uygulanan otomatik kenar boşluklarının boyutu cihazlar arasında farklılık gösterebilir. Kabaca tahmin yapmak için aşağıdaki tabloyu kullanın tipik bir 5x4 ızgara el cihazında widget'ınızın minimum boyutlarını istediğiniz dolu dolu ızgara hücresi sayısı:

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

Not: Önceki tabloda, hem dikey hem de yatay modlarda genel olarak kullanılabilen boyutların kaba tahminini göstermek için Google Pixel 4'te kullanılabilen boyutlar gösterilmektedir.

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

Bunun nedeni, hücre genişliğinin genellikle dikey modda yatay moddan daha küçük olması ve benzer şekilde hücre yüksekliğinin genellikle yatay modda dikey moddan daha küçük olmasıdı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 bir şekilde, widget yüksekliğinizin aynı cihazda dinleyebilmeniz için minResizeHeight cihazınızı en fazla 50 dp'ye ayarlamanız gerekir. minResizeHeight özelliğinin değeri şundan küçüktür: 51 dp: Yatay modda bir hücre en az 51 dp yüksekliğinde olduğundan.

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.

Not: Daha önce de belirtildiği gibi, widget'ın boyutunun maxResizeWidth x maxResizeHeight'ten büyük olması mümkündür. Widget boyutlandırma bölümüne bakın özellikleri hakkında daha fazla bilgi edinin.

Örneğin, yerleşimdeki widget'ın varsayılan boyutunu ayarlamak için aşağıdaki özellikleri ayarlayabilirsiniz:

<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 tarafından belirtildiği gibi 3x2 hücre olduğu veya Android 11 veya daha eski sürümleri çalıştıran cihazlar için minWidth ve minHeight tarafından belirtildiği gibi 180x110 dp olduğu anlamına gelir. İ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'den 530 dp'ye ve yüksekliği 110 dp'den 450 dp'ye yeniden boyutlandırılabilir. Daha sonra widget, aşağıdaki koşullar geçerli olduğu sürece 3x2 boyutundan 5x2 hücrelere yeniden boyutlandırılabilir. koşulların mevcut olması durumunda:

• 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 kod snippet'lerinde tanımlanan duyarlı düzenleri kullandığını varsayalım. 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. Aynı şekilde, R.layout.widget_weather_forecast_medium, 270x110 dp ile 270x279 dp arasında kullanılır, R.layout.widget_weather_forecast_large, 270x280 dp ile 530dp (maxResizeWidth) x 450dp (maxResizeHeight).

Kullanıcı widget'ı yeniden boyutlandırdığında, görünümü değişen her boyuta uyum sağlayacak şekilde hücrelerinin özelliklerini içerir.

Şekil 2. 3x2 R.layout.widget_weather_forecast_small.

Şekil 3. 4x2 R.layout.widget_weather_forecast_medium.

Şekil 4. 5x2 R.layout.widget_weather_forecast_medium.

Şekil 5. 5x3 R.layout.widget_weather_forecast_large.

Şekil 6. 5x4 R.layout.widget_weather_forecast_large.