विजेट के हिसाब से लेआउट उपलब्ध कराएं

यह पेज विजेट के साइज़ को बेहतर बनाने और ज़्यादा सहूलियत के लिए काम करता है इसे Android 12 (एपीआई लेवल 31) में लॉन्च किया गया है. इसमें अपने विजेट का साइज़ तय करने के तरीके के बारे में भी बताया गया है.

विजेट के साइज़ और लेआउट के लिए, बेहतर एपीआई इस्तेमाल करें

Android 12 (एपीआई लेवल 31) से, साइज़ के बेहतर एट्रिब्यूट और फ़्लेक्सिबल लेआउट दिए जा सकते हैं. इसके लिए, यहां दिए गए निर्देशों का पालन करें:

1. विजेट के साइज़ से जुड़ी अन्य सीमाएं तय करें.

2. प्रतिक्रियाशील लेआउट या सटीक उपलब्ध कराकर लेआउट.

Android के पिछले वर्शन में, तो विजेट OPTION_APPWIDGET_MIN_WIDTH, OPTION_APPWIDGET_MIN_HEIGHT OPTION_APPWIDGET_MAX_WIDTH, और OPTION_APPWIDGET_MAX_HEIGHT अतिरिक्त सुविधाएं जोड़ें और फिर विजेट के साइज़ का अनुमान लगाएं, लेकिन यह लॉजिक स्थितियों के बारे में बताना. Android 12 या उसके बाद के वर्शन को टारगेट करने वाले विजेट के लिए, हमारा सुझाव है कि रिस्पॉन्सिव (स्क्रीन के हिसाब से आकार बदलने वाले) या सटीक (सटीक) में जवाब देता है लेआउट शामिल करें.

विजेट के साइज़ की अतिरिक्त सीमाएं तय करें

Android 12 में एपीआई जोड़े गए हैं. इनकी मदद से, यह पक्का किया जा सकता है कि अलग-अलग स्क्रीन साइज़ वाले डिवाइसों पर, आपके विजेट का साइज़ ज़्यादा भरोसेमंद तरीके से तय किया जाए.

मौजूदा minWidth, minHeight, minResizeWidth, और minResizeHeight एट्रिब्यूट के अलावा, इन नए appwidget-provider एट्रिब्यूट का इस्तेमाल करें:

• targetCellWidth और targetCellHeight: इनकी मदद से, लॉन्चर ग्रिड सेल के हिसाब से विजेट का टारगेट साइज़ तय किया जाता है. अगर ये एट्रिब्यूट तय किए जाते हैं, तो minWidth या minHeight के बजाय इनका इस्तेमाल किया जाता है.

• maxResizeWidth और maxResizeHeight: लॉन्चर के ज़रिए उपयोगकर्ता को विजेट का ज़्यादा से ज़्यादा जिस साइज़ तक बदलने की अनुमति देता है उसे तय करें.

नीचे दिए गए एक्सएमएल में, साइज़िंग एट्रिब्यूट इस्तेमाल करने का तरीका बताया गया है.

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

रिस्पॉन्सिव लेआउट उपलब्ध कराना

अगर विजेट के साइज़ के हिसाब से लेआउट में बदलाव करना है, तो हमारा सुझाव है कि आप लेआउट का एक छोटा सेट बनाएं. हर लेआउट, साइज़ की एक रेंज के लिए मान्य होना चाहिए. अगर ऐसा करना संभव नहीं है, तो रनटाइम के दौरान विजेट के सटीक साइज़ के आधार पर लेआउट उपलब्ध कराने का विकल्प भी है. इस बारे में इस पेज पर बताया गया है.

इस सुविधा से, स्केलिंग और सिस्टम को बेहतर बनाया जाता है स्वास्थ्य, क्योंकि सिस्टम को हर बार ऐप को चालू नहीं करना पड़ता तो यह विजेट को अलग साइज़ में दिखाता है.

नीचे दिए गए कोड के उदाहरण में, लेआउट की सूची देने का तरीका बताया गया है.

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

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

मान लें कि विजेट में ये एट्रिब्यूट मौजूद हैं:

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

ऊपर दिए गए कोड स्निपेट का मतलब यह है:

• smallView 160dp (minResizeWidth) × 110dp के साथ काम करता है (minResizeHeight) से 160dp × 199dp (अगला कटऑफ़ पॉइंट - 1dp).
• tallView 160dp × 200dp से लेकर 214dp (अगला कटऑफ़ पॉइंट - 1) × 200dp तक के साइज़ के साथ काम करता है.

• wideView 215dp × 110dp (minResizeHeight) से लेकर 250dp (maxResizeWidth) × 200dp (maxResizeHeight) तक के साइज़ के साथ काम करता है.

आपके विजेट का साइज़, minResizeWidth × से ज़्यादा होना चाहिए minResizeHeight से maxResizeWidth × maxResizeHeight. इस सीमा में, लेआउट स्विच करने के लिए, आपके पास कटऑफ़ पॉइंट तय करने का विकल्प होता है.

सटीक लेआउट दें

अगर रिस्पॉन्सिव लेआउट का छोटा सेट उपलब्ध नहीं है, तो विजेट को दिखाए जाने वाले साइज़ के हिसाब से अलग-अलग लेआउट दिए जा सकते हैं. यह है आम तौर पर, फ़ोन के लिए दो साइज़ (पोर्ट्रेट और लैंडस्केप मोड) और फ़ोल्ड किए जा सकने वाले डिवाइस.

इस तरीके को लागू करने के लिए, आपके ऐप्लिकेशन को ये काम करने होंगे:

1. ओवरलोड AppWidgetProvider.onAppWidgetOptionsChanged(), जिसे साइज़ के सेट में बदलाव होने पर कॉल किया जाता है.

2. AppWidgetManager.getAppWidgetOptions() पर कॉल करें, जो साइज़ वाले Bundle नतीजे दिखाता है.

3. Bundle से AppWidgetManager.OPTION_APPWIDGET_SIZES कुंजी को ऐक्सेस करें.

नीचे दिए गए कोड के उदाहरण में, सटीक लेआउट देने का तरीका बताया गया है.

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 { }

@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) { }

अपने विजेट का साइज़ तय करें

हर विजेट के लिए, Android 12 या इसके बाद के वर्शन वाले डिवाइसों के लिए targetCellWidth और targetCellHeight या Android के सभी वर्शन के लिए minWidth और minHeight तय करना ज़रूरी है. इससे यह पता चलता है कि डिफ़ॉल्ट रूप से, विजेट में कम से कम कितना स्टोरेज इस्तेमाल होता है. हालांकि, जब उपयोगकर्ता अपनी होम स्क्रीन पर कोई विजेट जोड़ते हैं, तो आम तौर पर वह आपकी तय की गई कम से कम चौड़ाई और ऊंचाई से ज़्यादा जगह ले लेता है.

Android होम स्क्रीन पर, उपयोगकर्ताओं को उपलब्ध जगहों का ग्रिड दिखता है. इस ग्रिड पर, वे विजेट और आइकॉन डाल सकते हैं. यह ग्रिड, डिवाइस के हिसाब से अलग-अलग हो सकता है; उदाहरण के लिए, कई हैंडसेट 5x4 ग्रिड ऑफ़र करते हैं और टैबलेट बड़ी ग्रिड ऑफ़र कर सकते हैं. विजेट जोड़ने पर, उसे क्षैतिज और वर्टिकल तौर पर, कम से कम सेल में स्ट्रेच किया जाता है. ऐसा इसलिए किया जाता है, ताकि Android 12 या उसके बाद के वर्शन पर काम करने वाले डिवाइसों पर, targetCellWidth और targetCellHeight की सीमाओं को पूरा किया जा सके. इसके अलावा, Android 11 (एपीआई लेवल 30) या उससे पहले के वर्शन पर काम करने वाले डिवाइसों पर, minWidth और minHeight की सीमाओं को पूरा किया जा सके.

सेल की चौड़ाई और ऊंचाई, दोनों और विजेट पर लागू होने वाले अपने-आप मार्जिन का साइज़, अलग-अलग डिवाइसों पर अलग-अलग हो सकता है. मोटे तौर पर अनुमान लगाने के लिए, नीचे दी गई टेबल का इस्तेमाल करें आपके विजेट के कम से कम डाइमेंशन, सामान्य 5x4 ग्रिड हैंडसेट में होते हैं. व्यस्त ग्रिड सेल की संख्या:

अपनी तय की गई वैल्यू के बारे में बताने के लिए, पोर्ट्रेट मोड वाले सेल के साइज़ का इस्तेमाल करें minWidth, minResizeWidth, और maxResizeWidth एट्रिब्यूट. इसी तरह, minHeight, minResizeHeight, और maxResizeHeight एट्रिब्यूट के लिए दी गई वैल्यू की जानकारी देने के लिए, लैंडस्केप मोड में सेल के साइज़ का इस्तेमाल करें.

इसकी वजह यह है कि पोर्ट्रेट मोड में सेल की चौड़ाई आम तौर पर कम होती है की तुलना में लैंडस्केप मोड के मुकाबले काम करती है—और इसी तरह सेल की ऊंचाई आम तौर पर लैंडस्केप मोड में पोर्ट्रेट मोड से छोटा होता है.

उदाहरण के लिए, अगर आपको Google Pixel 4 पर अपने विजेट की चौड़ाई को एक सेल तक छोटा करना है, तो आपको minResizeWidth को ज़्यादा से ज़्यादा 56dp पर सेट करना होगा. इससे यह पक्का किया जा सकेगा कि minResizeWidth एट्रिब्यूट की वैल्यू 57dp से कम हो, क्योंकि पोर्ट्रेट मोड में एक सेल की चौड़ाई कम से कम 57dp होती है. इसी तरह, अगर आपको एक ही डिवाइस पर एक सेल में विजेट की ऊंचाई को फिर से साइज़ करना है, तो आपको minResizeHeight को ज़्यादा से ज़्यादा 50dp पर सेट करना होगा. इससे यह पक्का किया जा सकेगा कि minResizeHeight एट्रिब्यूट की वैल्यू 51dp से कम हो, क्योंकि लैंडस्केप मोड में एक सेल की ऊंचाई कम से कम 51dp होती है.

हर विजेट का साइज़ इन चीज़ों के बीच की साइज़ रेंज में बदला जा सकता है minResizeWidth/minResizeHeight और maxResizeWidth/maxResizeHeight एट्रिब्यूट का इस्तेमाल किया जाता है, जिसका मतलब है कि यह उनके बीच के किसी भी साइज़ की रेंज के हिसाब से होना चाहिए.

उदाहरण के लिए, प्लेसमेंट पर विजेट का डिफ़ॉल्ट साइज़ सेट करने के लिए, ये एट्रिब्यूट सेट करें:

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

इसका मतलब है कि विजेट का डिफ़ॉल्ट साइज़ 3x2 सेल है, जैसा कि targetCellWidth और targetCellHeight एट्रिब्यूट के ज़रिए बताया गया है. इसके अलावा, Android 11 या उससे पहले के वर्शन वाले डिवाइसों के लिए, विजेट का साइज़ 180×110dp है, जैसा कि minWidth और minHeight एट्रिब्यूट के ज़रिए बताया गया है. बाद वाले मामले में, सेल का आकार अलग-अलग हो सकते हैं.

साथ ही, अपने विजेट के लिए सही साइज़ रेंज सेट करने के लिए, ये चीज़ें सेट की जा सकती हैं: विशेषताएं:

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

जैसा कि पहले वाले एट्रिब्यूट में बताया गया है, बैज की चौड़ाई 180dp से 530dp तक का साइज़ बदला जा सकता है. इसकी ऊंचाई 110dp से 450dp तक बदली जा सकती है. इसके बाद, विजेट को 3x2 से 5x2 सेल तक का बनाया जा सकता है. हालांकि, इसके लिए ये शर्तें पूरी होनी चाहिए:

• डिवाइस में 5x4 ग्रिड हो.
• सेल की संख्या और डीपीएस में उपलब्ध साइज़ के बीच मैपिंग, इस पेज पर कम से कम डाइमेंशन का अनुमान दिखाने वाली टेबल के हिसाब से होती है.
• विजेट, उस साइज़ रेंज के हिसाब से अडजस्ट हो जाता है.

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

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

मान लें कि विजेट उन रिस्पॉन्सिव लेआउट का इस्तेमाल करता है जिनके बारे में पहले बताया गया है कोड स्निपेट. इसका मतलब है कि R.layout.widget_weather_forecast_small के तौर पर तय किए गए लेआउट का इस्तेमाल, 180dp (minResizeWidth) x 110dp (minResizeHeight) से लेकर 269x279dp (अगले कटऑफ़ पॉइंट - 1) तक किया जाता है. इसी तरह, R.layout.widget_weather_forecast_medium का इस्तेमाल 270x110dp से 270x279dp तक किया जाता है. साथ ही, R.layout.widget_weather_forecast_large का इस्तेमाल 270x280dp से लेकर 530dp (maxResizeWidth) x 450dp (maxResizeHeight) तक किया जाता है.

जैसे-जैसे उपयोगकर्ता विजेट का साइज़ बदलता है, विजेट का लुक, हर साइज़ के हिसाब से बदलता रहता है सेल भी देखें, जैसा कि नीचे दिए गए उदाहरणों में दिखाया गया है.