विजेट चुनने वाले टूल में, जनरेट की गई झलकें जोड़ना

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

अपने ऐप्लिकेशन के विजेट पिकर को बेहतर बनाने के लिए, Android 15 और उसके बाद के वर्शन वाले डिवाइसों पर जनरेट किए गए विजेट की झलक दिखाएं. साथ ही, Android 12 से Android 14 वाले डिवाइसों के लिए, स्केल किए गए विजेट की झलक दिखाएं. इसके लिए, previewLayout तय करें. इसके अलावा, पुराने वर्शन के लिए previewImage तय करें.

ज़्यादा जानकारी के लिए, YouTube पर लाइव अपडेट और विजेट की मदद से अपने ऐप्लिकेशन को बेहतर बनाएं लेख पढ़ें.

जनरेट किए गए विजेट की झलक दिखाने के लिए, अपना ऐप्लिकेशन सेट अप करना

Android 15 या उसके बाद के वर्शन वाले डिवाइस पर, जनरेट किए गए विजेट की झलक दिखाने के लिए, सबसे पहले मॉड्यूल build.gradle फ़ाइल में compileSdk की वैल्यू को 35 या उसके बाद के वर्शन पर सेट करें. इससे विजेट पिकर को RemoteViews देने की सुविधा मिलेगी

इसके बाद, ऐप्लिकेशन setWidgetPreview का इस्तेमाल GlanceAppWidgetManager या AppWidgetManager में कर सकते हैं. गलत इस्तेमाल को रोकने और सिस्टम की सेहत से जुड़ी समस्याओं को कम करने के लिए, setWidgetPreview एक ऐसा एपीआई है जिस पर अनुरोधों की संख्या सीमित होती है. डिफ़ॉल्ट सीमा के तौर पर, हर घंटे में करीब दो कॉल किए जा सकते हैं.

Jetpack Glance की मदद से, अपडेट की गई झलक जनरेट करना

Jetpack Glance की मदद से बनाए गए विजेट के लिए, यह तरीका अपनाएं:

1. झलक के लिए कंपोज़ेबल कॉन्टेंट देने के लिए, GlanceAppWidget.providePreview फ़ंक्शन को बदलें. provideGlance में जिस तरह से ऐप्लिकेशन का डेटा लोड किया जाता है उसी तरह से लोड करें. इसके बाद, उसे विजेट के कॉन्टेंट कंपोज़ेबल में पास करें, ताकि झलक में सटीक डेटा दिखे. provideGlance के उलट, यह एक सिंगल कंपोज़िशन है. इसमें कोई रीकंपोज़िशन या इफ़ेक्ट नहीं है.

2. झलक जनरेट करने और उसे पब्लिश करने के लिए, GlanceAppWidgetManager.setWidgetPreviews को कॉल करें.

झलक दिखाने के लिए, सिस्टम से कोई कॉलबैक नहीं होता है. इसलिए, आपके ऐप्लिकेशन को यह तय करना होगा कि setWidgetPreviews को कब कॉल करना है. अपडेट करने की रणनीति, आपके विजेट के इस्तेमाल के उदाहरण पर निर्भर करती है:

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

जनरेट की गई झलक से जुड़ी समस्या हल करना

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

ऐसा इसलिए होता है, क्योंकि Android डिफ़ॉल्ट रूप से सिर्फ़ उन कंपोज़ेबल को रेंडर करता है जो विजेट के कम से कम साइज़ पर दिखते हैं. दूसरे शब्दों में कहें, तो Android डिफ़ॉल्ट रूप से previewSizeMode को SizeMode.Single पर सेट करता है. यह ऐप्लिकेशन विजेट उपलब्ध कराने वाले ऐप्लिकेशन की जानकारी देने वाले XML में android:minHeight और android:minWidth का इस्तेमाल करता है, ताकि यह तय किया जा सके कि किन कंपोज़ेबल को ड्रा करना है.

इस समस्या को ठीक करने के लिए, GlanceAppWidget एट्रिब्यूट की वैल्यू को GlanceAppWidget एट्रिब्यूट की वैल्यू से बदलें और इसे SizeMode.Responsive पर सेट करें. साथ ही, DpSize एट्रिब्यूट की वैल्यू का सेट उपलब्ध कराएं.previewSizeMode इससे Android को, झलक दिखाने के लिए सभी लेआउट साइज़ के बारे में पता चलता है. इससे यह पक्का होता है कि सभी एलिमेंट सही तरीके से दिखें.

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

Jetpack Glance के बिना अपडेट की गई झलक जनरेट करना

Glance के बिना भी RemoteViews का इस्तेमाल किया जा सकता है. यहां दिए गए उदाहरण में, एक्सएमएल विजेट लेआउट रिसॉर्स लोड किया गया है और उसे पूर्वावलोकन के तौर पर सेट किया गया है. इस स्निपेट में setWidgetPreview को एक तरीके के तौर पर दिखाने के लिए, compileSdk की बिल्ड सेटिंग 35 या उसके बाद की होनी चाहिए.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

विजेट पिकर में, ज़रूरत के हिसाब से बड़े किए जा सकने वाले विजेट की झलक जोड़ना

Android 12 से, विजेट पिकर में दिखने वाली विजेट की झलक को बड़ा या छोटा किया जा सकता है. इसे एक्सएमएल लेआउट के तौर पर उपलब्ध कराया जाता है. यह विजेट के डिफ़ॉल्ट साइज़ पर सेट होता है. इससे पहले, विजेट की झलक एक स्टैटिक ड्रॉएबल रिसॉर्स थी. कुछ मामलों में, इससे झलक में यह जानकारी सही तरीके से नहीं दिखती थी कि विजेट को होम स्क्रीन पर जोड़ने के बाद वे कैसे दिखते हैं.

स्केल किए जा सकने वाले विजेट की झलक दिखाने के लिए, appwidget-provider एलिमेंट के previewLayout एट्रिब्यूट का इस्तेमाल करें. इससे एक्सएमएल लेआउट उपलब्ध कराया जा सकेगा:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

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

हमारा सुझाव है कि आप previewLayout और previewImage, दोनों एट्रिब्यूट की वैल्यू दें. इससे, अगर उपयोगकर्ता के डिवाइस पर previewLayout काम नहीं करता है, तो आपका ऐप्लिकेशन previewImage का इस्तेमाल कर सकेगा. previewLayout एट्रिब्यूट को previewImage एट्रिब्यूट की जगह प्राथमिकता दी जाती है.

विजेट की झलक दिखाने की सुविधा के साथ पुराने सिस्टम के साथ काम करने की सुविधा

Android 11 (एपीआई लेवल 30) या इससे पहले के वर्शन पर, विजेट पिकर को अपने विजेट की झलक दिखाने की अनुमति दें. इसके अलावा, जनरेट की गई झलकियों के लिए फ़ॉलबैक के तौर पर, previewImage एट्रिब्यूट की वैल्यू दें.

विजेट के दिखने के तरीके में बदलाव करने पर, झलक वाली इमेज को अपडेट करें.

डाइनैमिक आइटम शामिल करके, सटीक झलक बनाना

इस सेक्शन में, कलेक्शन व्यू वाले विजेट के लिए, विजेट की झलक में एक से ज़्यादा आइटम दिखाने का सुझाव दिया गया है. कलेक्शन व्यू वाले विजेट का मतलब है कि वह विजेट, ListView, GridView या StackView का इस्तेमाल करता है. यह जनरेट की गई विजेट की झलक पर लागू नहीं होता.

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

हमारा सुझाव है कि आप सिर्फ़ झलक के लिए बनाई गई एक अलग लेआउट फ़ाइल का इस्तेमाल करें. इससे, कलेक्शन व्यू वाले विजेट की झलक, विजेट पिकर में ठीक से दिखेगी. इस अलग लेआउट फ़ाइल में यह जानकारी शामिल होनी चाहिए:

• विजेट का असल लेआउट.
• फ़र्ज़ी आइटम के साथ प्लेसहोल्डर कलेक्शन व्यू. उदाहरण के लिए, कई नकली लिस्ट आइटम के साथ प्लेसहोल्डर LinearLayout देकर, ListView की नकल की जा सकती है.

ListView के लिए उदाहरण दिखाने के लिए, अलग लेआउट फ़ाइल से शुरू करें:

// res/layout/widget_preview.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:background="@drawable/widget_background"
   android:orientation="vertical">

    // Include the actual widget layout that contains ListView.
    <include
        layout="@layout/widget_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    // The number of fake items you include depends on the values you provide
    // for minHeight or targetCellHeight in the AppWidgetProviderInfo
    // definition.

    <TextView android:text="@string/fake_item1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

    <TextView android:text="@string/fake_item2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

</LinearLayout>

previewLayout मेटाडेटा का previewLayout एट्रिब्यूट देते समय, झलक दिखाने के लिए लेआउट फ़ाइल तय करें.AppWidgetProviderInfo आपको अब भी initialLayout एट्रिब्यूट के लिए, विजेट का असल लेआउट तय करना होगा. साथ ही, रनटाइम के दौरान RemoteViews बनाते समय, विजेट के असल लेआउट का इस्तेमाल करना होगा.

<appwidget-provider
    previewLayout="@layout/widget_previe"
    initialLayout="@layout/widget_view" />

सूची में शामिल जटिल आइटम

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

सूची के ऐसे आइटम पर विचार करें जिसे widget_list_item.xml में तय किया गया है और जिसमें दो TextView ऑब्जेक्ट शामिल हैं:

<LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_title" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_content" />
</LinearLayout>

सूची में फ़र्ज़ी आइटम दिखाने के लिए, लेआउट को कई बार शामिल किया जा सकता है. हालांकि, इससे सूची के सभी आइटम एक जैसे दिखते हैं. सूची में शामिल आइटम के लिए यूनीक आईडी देने के लिए, यह तरीका अपनाएं:

1. टेक्स्ट वैल्यू के लिए एट्रिब्यूट का सेट बनाएं:

   <resources>
       <attr name="widgetTitle" format="string" />
       <attr name="widgetContent" format="string" />
   </resources>
   

2. टेक्स्ट सेट करने के लिए, इन एट्रिब्यूट का इस्तेमाल करें:

   <LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
           android:layout_width="match_parent"
           android:layout_height="wrap_content">
   
       <TextView android:id="@id/title"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetTitle" />
   
       <TextView android:id="@id/content"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetContent" />
   </LinearLayout>
   

3. झलक के लिए, ज़रूरत के हिसाब से कई स्टाइल बनाएं. हर स्टाइल में वैल्यू फिर से तय करें:

   <resources>
   
       <style name="Theme.Widget.ListItem">
           <item name="widgetTitle"></item>
           <item name="widgetContent"></item>
       </style>
       <style name="Theme.Widget.ListItem.Preview1">
           <item name="widgetTitle">Fake Title 1</item>
           <item name="widgetContent">Fake content 1</item>
       </style>
       <style name="Theme.Widget.ListItem.Preview2">
           <item name="widgetTitle">Fake title 2</item>
           <item name="widgetContent">Fake content 2</item>
       </style>
   
   </resources>
   

4. झलक वाले लेआउट में मौजूद नकली आइटम पर स्टाइल लागू करें:

   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
      android:layout_width="match_parent"
      android:layout_height="wrap_content" ...>
   
       <include layout="@layout/widget_view" ... />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview1" />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview2" />
   
   </LinearLayout>