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

इस पेज पर, 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, 160 डीपी (minResizeWidth) × 110 डीपी (minResizeHeight) से लेकर 160 डीपी × 199 डीपी (अगला कटऑफ़ पॉइंट - 1 डीपी) तक काम करता है.
• 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) तक किया जाता है.

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