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

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

अपने ऐप्लिकेशन के विजेट पिकर को बेहतर बनाने के लिए, 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 में previewSizeMode को बदलें और इसे SizeMode.Responsive पर सेट करें. साथ ही, DpSize वैल्यू का सेट उपलब्ध कराएं. इससे Android को, झलक दिखाने के लिए ज़रूरी सभी लेआउट साइज़ के बारे में पता चलता है. इससे यह पक्का होता है कि सभी एलिमेंट सही तरीके से दिखें.

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

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

Glance के बिना भी RemoteViews का इस्तेमाल किया जा सकता है. यहां दिए गए उदाहरण में, एक्सएमएल विidget लेआउट रिसॉर्स को लोड किया गया है और उसे पूर्वावलोकन के तौर पर सेट किया गया है. इस स्निपेट में 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>