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

इस पेज पर, 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) तक किया जाता है.

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