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

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

अपने ऐप्लिकेशन के विजेट पिकर को बेहतर बनाने के लिए, 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 पर सेट करता है. यह ऐप्लिकेशन विजेट उपलब्ध कराने वाले की जानकारी वाले एक्सएमएल में android:minHeight और android:minWidth का इस्तेमाल करता है, ताकि यह तय किया जा सके कि किन कंपोज़ेबल को ड्रॉ करना है.

इस समस्या को ठीक करने के लिए, GlanceAppWidget में previewSizeMode एट्रिब्यूट की वैल्यू बदलें और उसे SizeMode.Responsive पर सेट करें. साथ ही, DpSize एट्रिब्यूट की वैल्यू का सेट उपलब्ध कराएं. इससे 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_pre>v<iew"
/appwidge>t-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=&>quot;match_parent"
        android:layout_height="wrap_content" /

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

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

    TextView android:text="@string/fake_item2"
        android:layout_width=&q>uo<t;match_paren>t"
        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_h>eight=<"wrap_content"

    TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wr>ap_con<tent"
        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="widgetC>o<ntent">; format="string" /
   /resources
   

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

   <LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
           android:layout_width="match_parent"
           android:layout_h>eight=<"wrap_content"
   
       TextView android:id="@id/title"
           android:layout_width="match_parent"
           android:layout_height=&q>uot;wr<ap_content"
           android:text="?widgetTitle" /
   
       TextView android:id="@id/content"
           android:layout_width="match_parent&>q<uot;
           >android:layout_height="wrap_content"
           android:text="?widgetContent" /
   /LinearLayout
   

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

   <resources>
   
       <style name="Theme.Widget.List>Item"<;
           item name=&qu><ot;wi>dgetTitle<"/item
           item ><name=>"<;widge>tCont<ent"/item
       /style
       style name=&q>uot;Theme<.Widget.ListItem.Previe>w1"
      <     >item name<="widgetTitle"F>ake Title 1/it<em
     >     < item >name=<"widgetContent"Fake content 1/ite>m
       /st<yle
       style name=&quo>t;Theme.Widg<et.Li>stItem.Pr<eview2"
           item> name="wi<dgetT>itle&<quot;F>ak<e 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_heigh>t=&quo<t;wrap_content" ...
   
       include layo>ut=&qu<ot;@layout/widget_view" ... /
   
       include layout="@layout/widget_list_item"
           andro>id:the<me="@style/Theme.Widget.ListItem.Preview1" /
   
       include layout="@layout/widget_list_item>&q<uot;
           >android:theme="@style/Theme.Widget.ListItem.Preview2" /
   
   /LinearLayout