अपने ऐप्लिकेशन के विजेट पिकर के अनुभव को बेहतर बनाने के लिए, Android 15 और उसके बाद के वर्शन वाले डिवाइसों पर, जनरेट की गई विजेट की झलक दिखाएं. साथ ही, Android 12 से Android 14 वाले डिवाइसों के लिए, स्केल की गई विजेट की झलक दिखाएं. इसके लिए, previewLayout की वैल्यू दें. इसके अलावा, पहले के वर्शन के लिए previewImage की वैल्यू दें.
जनरेट की गई विजेट की झलक की मदद से, अपने विजेट के लिए डाइनैमिक और लोगों की दिलचस्पी के हिसाब से झलक बनाई जा सकती हैं. इससे यह सही तरीके से पता चलता है कि विजेट, किसी व्यक्ति की होम स्क्रीन पर कैसे दिखेंगे. Android 15 और उसके बाद के वर्शन के लिए, इन्हें पुश एपीआई के ज़रिए उपलब्ध कराया जाता है. इसका मतलब है कि आपका ऐप्लिकेशन, अपने लाइफ़साइकल के दौरान किसी भी समय झलक दिखा सकता है. इसके लिए, उसे विजेट होस्ट से साफ़ तौर पर अनुरोध पाने की ज़रूरत नहीं होती.
ज़्यादा जानकारी के लिए, YouTube पर अपने ऐप्लिकेशन में लाइव अपडेट और विजेट जोड़ना लेख पढ़ें.
जनरेट की गई झलक जोड़ना
Android 15 या उसके बाद के वर्शन वाले डिवाइस पर, जनरेट की गई विजेट की झलक दिखाने के लिए, सबसे पहले मॉड्यूल की build.gradle फ़ाइल में
compileSdk की वैल्यू 35 या उससे ज़्यादा सेट करें. इससे, विजेट पिकर को RemoteViews उपलब्ध कराने की
सुविधा मिलेगी
ऐप्लिकेशन, setWidgetPreview का इस्तेमाल AppWidgetManager में कर सकते हैं. गलत इस्तेमाल को रोकने और सिस्टम की सेहत से जुड़ी समस्याओं को कम करने के लिए, setWidgetPreview एक रेट-लिमिट वाला एपीआई है.
डिफ़ॉल्ट तौर पर, इसकी सीमा हर घंटे में करीब दो कॉल होती है.
झलक दिखाने के लिए, सिस्टम से कोई कॉलबैक नहीं होता. इसलिए, आपके ऐप्लिकेशन को यह तय करना होगा कि setWidgetPreviews का इस्तेमाल कब करना है. अपडेट करने की रणनीति, आपके विजेट के इस्तेमाल के उदाहरण पर निर्भर करती है:
- अगर विजेट में स्थायी जानकारी है या वह झटपट कार्रवाई करने वाला विजेट है, तो ऐप्लिकेशन को पहली बार लॉन्च करने पर, विजेट की झलक सेट करें.
- आपका ऐप्लिकेशन डेटा मिलने के बाद, झलक सेट की जा सकती है. जैसे, उपयोगकर्ता के साइन इन करने या शुरुआती सेटअप के बाद.
- चुनी गई कैडेंस पर झलक अपडेट करने के लिए, समय-समय पर होने वाला टास्क सेट किया जा सकता है.
यहां दिए गए उदाहरण में, एक्सएमएल विजेट लेआउट रिसॉर्स लोड किया जाता है और उसे झलक के तौर पर सेट किया जाता है. इस स्निपेट में setWidgetPreview को एक तरीके के तौर पर दिखाने के लिए, compileSdk की बिल्ड सेटिंग 35 या उसके बाद की होनी चाहिए.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
स्केल की जा सकने वाली विजेट की झलक जोड़ना
Android 12 से, विजेट पिकर में दिखने वाली विजेट की झलक को बड़ा या छोटा किया जा सकता है. इसे एक्सएमएल लेआउट के तौर पर उपलब्ध कराया जाता है. यह विजेट के डिफ़ॉल्ट साइज़ पर सेट होता है. इससे पहले, विजेट की झलक ड्रॉ करने लायक एक स्थायी संसाधन थी. कुछ मामलों में, झलक में यह सही तरीके से नहीं दिखता था कि विजेट को होम स्क्रीन पर जोड़ने के बाद वे कैसे दिखते हैं.
स्केल की जा सकने वाली विजेट की झलक लागू करने के लिए,
previewLayout
एट्रिब्यूट का इस्तेमाल करके, appwidget-provider एलिमेंट के बजाय एक्सएमएल लेआउट उपलब्ध कराएं:
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
हमारा सुझाव है कि असल विजेट के जैसा ही लेआउट इस्तेमाल करें. साथ ही, डिफ़ॉल्ट या टेस्ट वैल्यू को असल वैल्यू के तौर पर दिखाएं. ज़्यादातर ऐप्लिकेशन, एक ही previewLayout और initialLayout का इस्तेमाल करते हैं. सही झलक वाले लेआउट बनाने के बारे में जानकारी पाने के लिए, डाइनैमिक आइटम शामिल करने वाली सही झलक बनाना लेख पढ़ें.
हमारा सुझाव है कि आप previewLayout और previewImage, दोनों एट्रिब्यूट की वैल्यू दें. इससे, अगर उपयोगकर्ता के डिवाइस पर previewLayout काम नहीं करता है, तो आपका ऐप्लिकेशन previewImage का इस्तेमाल कर सकेगा. previewLayout एट्रिब्यूट को previewImage एट्रिब्यूट के ऊपर प्राथमिकता दी जाती है.
पीछे के वर्शन के साथ काम करने की सुविधा के लिए, स्थायी विजेट की झलक जोड़ना
Android 11 (एपीआई लेवल 30) या इससे पहले के वर्शन पर, विजेट पिकर को अपने
विजेट की झलक दिखाने की अनुमति देने और स्केल की जा सकने वाली झलक के फ़ॉलबैक के तौर पर भी इस एट्रिब्यूट का इस्तेमाल किया जा सकता है. इसके लिए, previewImage
एट्रिब्यूट की वैल्यू दें.
अगर विजेट की झलक में कोई बदलाव किया जाता है, तो झलक वाली इमेज को अपडेट करें.
अगर आपने setWidgetPreview का इस्तेमाल करके, जनरेट की गई झलक सेट नहीं की है, तो इस एट्रिब्यूट का इस्तेमाल फ़ॉलबैक के तौर पर भी किया जाता है.
डाइनैमिक आइटम शामिल करने वाली सही झलक बनाना
इस सेक्शन में, कलेक्शन व्यू वाले विजेट की झलक में एक से ज़्यादा आइटम दिखाने का सुझाव दिया गया है. कलेक्शन व्यू वाले विजेट का मतलब है, ऐसे विजेट जो ListView, GridView, या StackView का इस्तेमाल करते हैं. यह स्केल की जा सकने वाली विजेट की झलक पर लागू होता है, जनरेट की गई झलक पर नहीं.
अगर आपका विजेट इनमें से किसी एक व्यू का इस्तेमाल करता है, तो previewLayout में सीधे विजेट का असल लेआउट उपलब्ध कराकर, स्केल की जा सकने वाली झलक बनाने से, उपयोगकर्ता अनुभव खराब हो सकता है. ऐसा तब होता है, जब विजेट की झलक में कोई आइटम नहीं दिखता. ऐसा इसलिए होता है, क्योंकि कलेक्शन व्यू का डेटा, रनटाइम पर डाइनैमिक तौर पर सेट किया जाता है. यह पहली इमेज में दिखाई गई इमेज जैसा दिखता है.
विजेट पिकर में, कलेक्शन व्यू वाले विजेट की झलक सही तरीके से दिखाने के लिए, हमारा सुझाव है कि सिर्फ़ झलक के लिए एक अलग लेआउट फ़ाइल बनाए रखें. इस अलग लेआउट फ़ाइल में यह शामिल होना चाहिए:
- विजेट का असल लेआउट.
- फ़र्ज़ी आइटम के साथ प्लेसहोल्डर कलेक्शन व्यू. उदाहरण के लिए, कई फ़र्ज़ी लिस्ट आइटम के साथ प्लेसहोल्डर
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>
AppWidgetProviderInfo मेटाडेटा का previewLayout एट्रिब्यूट उपलब्ध कराते समय, झलक वाले लेआउट की फ़ाइल की जानकारी दें. अब भी initialLayout एट्रिब्यूट के लिए, विजेट का असल लेआउट तय करें. साथ ही, रनटाइम पर RemoteViews बनाते समय, विजेट के असल लेआउट का इस्तेमाल करें.
<appwidget-provider
previewLayout="@layout/widget_preview"
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>
फ़र्ज़ी लिस्ट आइटम उपलब्ध कराने के लिए, लेआउट को कई बार शामिल किया जा सकता है. हालांकि, इससे हर लिस्ट आइटम एक जैसा दिखता है. अलग-अलग लिस्ट आइटम उपलब्ध कराने के लिए, यह तरीका अपनाएं:
टेक्स्ट वैल्यू के लिए एट्रिब्यूट का सेट बनाएं:
<resources> <attr name="widgetTitle" format="string" /> <attr name="widgetContent" format="string" /> </resources>टेक्स्ट सेट करने के लिए, इन एट्रिब्यूट का इस्तेमाल करें:
<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>झलक के लिए, ज़रूरत के हिसाब से स्टाइल बनाएं. हर स्टाइल में वैल्यू फिर से तय करें:
<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>झलक वाले लेआउट में मौजूद फ़र्ज़ी आइटम पर स्टाइल लागू करें:
<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>