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

Compose को आज़माएं

Jetpack Compose, Android के लिए सुझाई गई यूज़र इंटरफ़ेस (यूआई) टूलकिट है. Compose-स्टाइल एपीआई का इस्तेमाल करके विजेट बनाने का तरीका जानें.

Jetpack Glance →

इस पेज पर, 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 xmlns:android="http://schemas.android.com/apk/res/android"
  android:targetCellWidth="3"
  android:targetCellHeight="2"
  android:maxResizeWidth="250dp"
  android:maxResizeHeight="110dp">
</appwidget-provider>
sizing_attributes.xml

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

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

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

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

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

    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)
}
Layouts.kt

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

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="160dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="200dp">
</appwidget-provider>
sizing_constraints.xml

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

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

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

  ध्यान दें: ऐसा हो सकता है कि विजेट का साइज़ maxResizeWidth × maxResizeHeight से बड़ा हो. ज़्यादा जानकारी के लिए, विजेट के साइज़ से जुड़े एट्रिब्यूट देखें.

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

पहली इमेज. रिस्पॉन्सिव लेआउट का उदाहरण.

सटीक लेआउट उपलब्ध कराना

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

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

1. Overload 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?.let {
        BundleCompat.getParcelableArrayList(
            it,
            AppWidgetManager.OPTION_APPWIDGET_SIZES,
            SizeF::class.java
        )
    }
    // 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 {
}
Layouts.kt

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

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

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

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

सेल की संख्या (चौड़ाई x ऊंचाई)	पोर्ट्रेट मोड में उपलब्ध साइज़ (डीपी)	लैंडस्केप मोड में उपलब्ध साइज़ (डीपी)
1x1	57x102dp	127x51dp
2x1	130x102dp	269x51dp
3x1	203x102dp	412x51dp
4x1	276x102dp	554x51dp
5x1	349x102dp	697x51dp
5x2	349x220dp	697x117dp
5x3	349x337dp	697x184dp
5x4	349x455dp	697x250dp
...	...	...
n x m	(73n - 16) x (118m - 16)	(142n - 15) x (66m - 15)

ध्यान दें: ऊपर दी गई टेबल में, Google Pixel 4 पर उपलब्ध साइज़ दिखाए गए हैं. इससे पोर्ट्रेट और लैंडस्केप, दोनों मोड में आम तौर पर उपलब्ध साइज़ का अनुमान लगाया जा सकता है.

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

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

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

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

ध्यान दें: जैसा कि पहले बताया गया है, विजेट का साइज़ maxResizeWidth x maxResizeHeight से बड़ा हो सकता है. ज़्यादा जानकारी के लिए, विजेट के साइज़ से जुड़े एट्रिब्यूट देखें.

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

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>
default_size_attributes.xml

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

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

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="180dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="530dp"
    android:maxResizeHeight="450dp">
</appwidget-provider>
supported_size_ranges.xml

ऊपर दिए गए एट्रिब्यूट के मुताबिक, विजेट की चौड़ाई को 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))
Layouts.kt

मान लें कि विजेट, ऊपर दिए गए कोड स्निपेट में बताए गए रिस्पॉन्सिव लेआउट का इस्तेमाल करता है. इसका मतलब है कि 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) तक किया जाता है.

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

दूसरी इमेज. 3x2 R.layout.widget_weather_forecast_small.

तीसरी इमेज. 4x2 R.layout.widget_weather_forecast_medium.

चौथी इमेज. 5x2 R.layout.widget_weather_forecast_medium.

पांचवीं इमेज. 5x3 R.layout.widget_weather_forecast_large.

छठी इमेज. 5x4 R.layout.widget_weather_forecast_large.