अपने विजेट को बेहतर बनाएं

इस पेज पर, विजेट को बेहतर बनाने के विकल्पों के बारे में जानकारी दी गई है. ये विकल्प, Android 12 (एपीआई लेवल 31) से उपलब्ध हैं. ये सुविधाएं ज़रूरी नहीं हैं. हालांकि, इन्हें लागू करना और उपयोगकर्ताओं को विजेट का बेहतर अनुभव देना आसान है.

डाइनैमिक रंगों का इस्तेमाल करना

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

डाइनैमिक रंगों को दो तरीकों से इस्तेमाल किया जा सकता है:

• रूट लेआउट में, सिस्टम की डिफ़ॉल्ट थीम (@android:style/Theme.DeviceDefault.DayNight) का इस्तेमाल करें.

• Android के लिए मटीरियल कॉम्पोनेंट लाइब्रेरी से, Material 3 थीम (Theme.Material3.DynamicColors.DayNight) का इस्तेमाल करें. यह थीम, Android के लिए मटीरियल कॉम्पोनेंट के v1.6.0 वर्शन से उपलब्ध है.

रूट लेआउट में थीम सेट करने के बाद, रूट या उसके किसी भी चाइल्ड एट्रिब्यूट में कलर एट्रिब्यूट का इस्तेमाल करके, डाइनैमिक कलर चुने जा सकते हैं.

रंग के एट्रिब्यूट के कुछ उदाहरण यहां दिए गए हैं:

• ?attr/primary
• ?attr/primaryContainer
• ?attr/onPrimary
• ?attr/onPrimaryContainer

यहां दिए गए उदाहरण में, Material 3 थीम का इस्तेमाल किया गया है. इसमें डिवाइस की थीम का रंग "बैंगनी" है. ऐक्सेंट कलर और विजेट का बैकग्राउंड, हल्के और गहरे रंग वाले मोड के हिसाब से अडजस्ट हो जाता है. इसकी जानकारी, पहले और दूसरे फ़ोटो में दी गई है.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>

डाइनैमिक कलर के लिए पुराने सिस्टम के साथ काम करने की सुविधा

डाइनैमिक कलर की सुविधा, सिर्फ़ Android 12 या इसके बाद के वर्शन वाले डिवाइसों पर उपलब्ध है. पुराने वर्शन के लिए कस्टम थीम उपलब्ध कराने के लिए, अपनी पसंद के रंगों का इस्तेमाल करके एक डिफ़ॉल्ट थीम बनाएं. साथ ही, डिफ़ॉल्ट थीम एट्रिब्यूट का इस्तेमाल करके नया क्वालीफ़ायर (values-v31) बनाएं.

यहां Material 3 थीम का इस्तेमाल करने का उदाहरण दिया गया है:

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

बोलकर निर्देश देने की सुविधा चालू करना

ऐप्लिकेशन ऐक्शन की मदद से, Google Assistant उपयोगकर्ता की बोली गई ज़रूरी निर्देशों के जवाब में विजेट दिखाती है. पहले से मौजूद इंटेंट (बीआईआई) का जवाब देने के लिए, अपने विजेट को कॉन्फ़िगर करें. इससे आपका ऐप्लिकेशन, Android और Android Auto जैसे Assistant प्लैटफ़ॉर्म पर विजेट दिखा सकता है. उपयोगकर्ताओं के पास, Assistant के दिखाए गए विजेट को पिन करने का विकल्प होता है. इससे, आने वाले समय में उपयोगकर्ताओं की दिलचस्पी बढ़ती है.

उदाहरण के लिए, कसरत की खास जानकारी वाले विजेट को अपने कसरत से जुड़े ऐप्लिकेशन के लिए कॉन्फ़िगर किया जा सकता है. इससे उपयोगकर्ता के बोले गए निर्देशों को पूरा किया जा सकता है. ये निर्देश GET_EXERCISE_OBSERVATION बीआईआई को ट्रिगर करते हैं. जब उपयोगकर्ता इस बीआईआई को ट्रिगर करते हैं, तो Assistant आपका विजेट अपने-आप दिखाती है. ऐसा तब होता है, जब उपयोगकर्ता "Ok Google, मैंने इस हफ़्ते ExampleApp पर कितने मील दौड़ लगाई?" जैसे अनुरोध करते हैं.

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

अपने ऐप्लिकेशन के विजेट पिकर का अनुभव बेहतर बनाएं

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

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

विजेट पिकर में विजेट की जनरेट की गई झलक जोड़ें

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

ऐप्लिकेशन, अपने विजेट के दिखने के तरीके को अपडेट करने के लिए, AppWidgetManager, setWidgetPreview, और getWidgetPreview तरीकों का इस्तेमाल कर सकते हैं. इससे, विजेट में अप-टू-डेट और उपयोगकर्ता के हिसाब से जानकारी दिखती है.

Jetpack एक नज़र में जानकारी देखने की सुविधा की मदद से अपडेट की गई झलक जनरेट करें

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

यहां दिए गए उदाहरण में, अपडेट की गई झलक जनरेट करने के लिए Jetpack पेशेवर ऐप्लिकेशन का इस्तेमाल किया गया है. इस स्निपेट में setWidgetPreview को एक तरीके के तौर पर दिखाने के लिए, compileSdk की बिल्ड सेटिंग 35 या उसके बाद की होनी चाहिए.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)
AppWidgetSnippets.kt

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

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

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 एट्रिब्यूट पर प्राथमिकता दी जाती है.

सटीक झलक बनाने के लिए सुझाए गए तरीके

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

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

सटीक झलक दिखाने के लिए, डिफ़ॉल्ट वैल्यू के साथ सीधे तौर पर असल विजेट लेआउट दिया जा सकता है. इसके लिए, यह तरीका अपनाएं:

• TextView एलिमेंट के लिए android:text="@string/my_widget_item_fake_1" सेट करना.

• ImageView कॉम्पोनेंट के लिए, डिफ़ॉल्ट या प्लेसहोल्डर इमेज या आइकॉन सेट करना, जैसे कि android:src="@drawable/my_widget_icon".

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

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

बढ़ाने लायक विजेट की झलक के साथ पुराने सिस्टम के साथ काम करने की सुविधा

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

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

अपने विजेट को कोई नाम दें

विजेट पिकर में विजेट दिखाए जाने पर, उनका नाम यूनीक होना चाहिए.

विजेट के नाम, AndroidManifest.xml फ़ाइल में विजेट के receiver एलिमेंट की label एट्रिब्यूट से लोड किए जाते हैं.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

अपने विजेट के लिए जानकारी जोड़ना

Android 12 की शुरुआत में, अपने विजेट में विजेट दिखाने के लिए, जानकारी दें.

<appwidget-provider> एलिमेंट के description एट्रिब्यूट का इस्तेमाल करके, अपने विजेट की जानकारी दें:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

Android के पिछले वर्शन पर, descriptionRes एट्रिब्यूट का इस्तेमाल किया जा सकता है. हालांकि, विजेट पिकर इस एट्रिब्यूट को अनदेखा कर देता है.

आसान ट्रांज़िशन की सुविधा चालू करें

Android 12 से, जब कोई उपयोगकर्ता किसी विजेट से आपका ऐप्लिकेशन लॉन्च करता है, तो लॉन्चर आसानी से ट्रांज़िशन करते हैं.

बेहतर ट्रांज़िशन की सुविधा चालू करने के लिए, अपने बैकग्राउंड एलिमेंट की पहचान करने के लिए @android:id/background या android.R.id.background का इस्तेमाल करें:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

आपका ऐप्लिकेशन, Android के पुराने वर्शन पर @android:id/background का इस्तेमाल कर सकता है. हालांकि, इसकी अनदेखी की जाती है.

RemoteViews के रनटाइम में बदलाव करने की सुविधा का इस्तेमाल करना

Android 12 से, RemoteViews एट्रिब्यूट के रनटाइम में बदलाव करने के लिए, RemoteViews के कई तरीकों का फ़ायदा लिया जा सकता है. जोड़े गए तरीकों की पूरी सूची के लिए, RemoteViews एपीआई का रेफ़रंस देखें.

नीचे दिया गया उदाहरण कोड इनमें से कुछ तरीकों को इस्तेमाल करने का तरीका बताता है.

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);