विजेट होस्ट बनाएं

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

इस पेज पर, कस्टम AppWidgetHost लागू करने से जुड़ी ज़िम्मेदारियों के बारे में बताया गया है. AppWidgetHost को लागू करने के खास उदाहरण के लिए, Android की होम स्क्रीन का सोर्स कोड देखें LauncherAppWidgetHost.

कस्टम AppWidgetHost लागू करने में शामिल मुख्य क्लास और कॉन्सेप्ट की खास जानकारी यहां दी गई है:

  • ऐप्लिकेशन विजेट होस्ट: AppWidgetHost अपने यूज़र इंटरफ़ेस (यूआई) में विजेट एम्बेड करने वाले ऐप्लिकेशन के लिए, AppWidget की सेवा. AppWidgetHost एक आईडी होना चाहिए जो होस्ट के खुद के पैकेज में अद्वितीय हो. यह आईडी, होस्ट के सभी इस्तेमाल में बना रहता है. आम तौर पर, आईडी एक हार्डकोड वैल्यू होती है, जिसे असाइन करें.

  • ऐप्लिकेशन विजेट आईडी: बाइंड करने के समय, हर विजेट इंस्टेंस को एक यूनीक आईडी असाइन किया जाता है. यहां जाएं: bindAppWidgetIdIfAllowed() और ज़्यादा जानकारी के लिए, बाइंडिंग विजेट सेक्शन देखें. कॉन्टेंट बनाने होस्ट इसका इस्तेमाल करके यूनीक आईडी हासिल करता है allocateAppWidgetId(). यह आईडी, विजेट के पूरे लाइफ़टाइम तक बना रहता है. हालांकि, इसे होस्ट से मिटाने पर यह आईडी भी मिट जाता है. होस्ट से जुड़ी कोई भी खास स्थिति, जैसे कि होस्ट का साइज़ और जगह विजेट—इसे होस्टिंग पैकेज के साथ बनाए रखना चाहिए और ऐप्लिकेशन विजेट आईडी.

  • ऐप्लिकेशन विजेट होस्ट व्यू: AppWidgetHostView को एक फ़्रेम के तौर पर देखें. जब भी विजेट को दिखाना हो, तब उसे इस फ़्रेम में लपेटा जाता है. जब भी होस्ट किसी विजेट को इन्फ़्लेट करता है, तो वह विजेट किसी AppWidgetHostView से जुड़ जाता है.

    • डिफ़ॉल्ट रूप से, सिस्टम एक AppWidgetHostView बनाता है, लेकिन होस्ट ये काम कर सकता है AppWidgetHostView की अपनी सब-क्लास बनाने के लिए, उसे बढ़ाएं.
    • Android 12 (एपीआई लेवल 31) से, AppWidgetHostView में डाइनैमिक तौर पर ओवरलोड किए गए रंगों को मैनेज करने के लिए, setColorResources() और resetColorResources() तरीके उपलब्ध कराए गए हैं. होस्ट इन तरीकों का इस्तेमाल करने के लिए पूरी ज़िम्मेदारी लेते हैं.

  • विकल्पों का बंडल: AppWidgetHost इन कामों के लिए, विकल्प बंडल का इस्तेमाल करता है अपनी जानकारी को AppWidgetProvider विजेट किस तरह से दिखता है—उदाहरण के लिए, साइज़ रेंज की सूची—और क्या विजेट लॉकस्क्रीन या होम स्क्रीन पर हो. इस जानकारी से AppWidgetProvider विजेट के कॉन्टेंट और लुक को, जहां यह दिखता है. विजेट के बंडल में बदलाव करने के लिए, updateAppWidgetOptions() और updateAppWidgetSize() का इस्तेमाल किया जा सकता है. ये दोनों तरीके आपकी साइट पर ट्रैफ़िक onAppWidgetOptionsChanged() AppWidgetProvider पर कॉलबैक करें.

बाइंडिंग विजेट

जब कोई उपयोगकर्ता होस्ट में कोई विजेट जोड़ता है, तो बाइंडिंग की प्रोसेस शुरू होती है. बाइंडिंग किसी खास ऐप्लिकेशन विजेट आईडी को किसी खास होस्ट और खास AppWidgetProvider.

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

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

हालांकि, यह तो सिर्फ़ पहला कदम है. रनटाइम के दौरान, उपयोगकर्ता को आपके ऐप्लिकेशन को साफ़ तौर पर अनुमति देनी होगी, ताकि वह होस्ट में विजेट जोड़ सके. यह जांचने के लिए कि आपके ऐप्लिकेशन के पास विजेट जोड़ने की अनुमति है या नहीं, bindAppWidgetIdIfAllowed() के तरीके का इस्तेमाल करें. अगर bindAppWidgetIdIfAllowed(), false दिखाता है, तो आपके ऐप्लिकेशन को डायलॉग बॉक्स, जो उपयोगकर्ता को अनुमति देने के लिए कहता है: "अनुमति दें" मौजूदा विजेट के लिए जोड़ना या "हमेशा अनुमति देना" ताकि भविष्य में जोड़े जाने वाले सभी विजेट को शामिल किया जा सके.

इस स्निपेट में, डायलॉग दिखाने का तरीका बताया गया है:

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

होस्ट को यह जांच करनी होगी कि उपयोगकर्ता ने जिस विजेट को जोड़ा है उसे कॉन्फ़िगरेशन की ज़रूरत है या नहीं. ज़्यादा जानकारी के लिए, उपयोगकर्ताओं को ऐप्लिकेशन विजेट कॉन्फ़िगर करने की अनुमति देना लेख पढ़ें.

होस्ट की ज़िम्मेदारियां

आप विजेट के लिए कई कॉन्फ़िगरेशन सेटिंग निर्दिष्ट कर सकते हैं. AppWidgetProviderInfo मेटाडेटा. विजेट की सेवा देने वाली कंपनी से जुड़े AppWidgetProviderInfo ऑब्जेक्ट से, इन कॉन्फ़िगरेशन विकल्पों को वापस पाया जा सकता है. इन विकल्पों के बारे में यहां दिए गए सेक्शन में ज़्यादा जानकारी दी गई है.

Android के किसी भी वर्शन को टारगेट करने पर, सभी होस्ट के पास ये ज़िम्मेदारियां होती हैं:

  • विजेट जोड़ते समय, ऊपर बताए गए तरीके से विजेट आईडी असाइन करें. जब होस्ट से कोई विजेट हटाया जाता है, तो विजेट आईडी को डिलीगेट करने के लिए, deleteAppWidgetId() को कॉल करें.

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

  • विजेट, AppWidgetProviderInfo मेटाडेटा में डिफ़ॉल्ट चौड़ाई और ऊंचाई की जानकारी देते हैं. ये वैल्यू, सेल में तय की जाती हैं. अगर targetCellWidth और targetCellHeight की वैल्यू दी गई है, तो ये वैल्यू Android 12 से शुरू होती हैं. अगर सिर्फ़ minWidth और minHeight की वैल्यू दी गई है, तो ये वैल्यू डीपीएस में होती हैं. विजेट के साइज़ से जुड़े एट्रिब्यूट देखें.

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

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

टारगेट किए गए Android वर्शन के आधार पर, रणनीति तय करें

Android 12

Android 12 (एपीआई लेवल 31) के साथ, एक और List<SizeF> शामिल होता है, जिसमें यह सूची मौजूद होती है डीपी में संभावित साइज़ हैं जिन्हें विकल्प बंडल में विजेट इंस्टेंस ले सकता है. साइज़ की संख्या, होस्ट को लागू करने के तरीके के हिसाब से तय होती है. आम तौर पर, होस्ट फ़ोन के लिए दो आकार उपलब्ध कराते हैं—पोर्ट्रेट और लैंडस्केप—और चार आकार फ़ोल्डेबल डिवाइसों के लिए.

AppWidgetProvider, RemoteViews को ज़्यादा से ज़्यादा MAX_INIT_VIEW_COUNT (16) अलग-अलग RemoteViews दे सकता है. AppWidgetProvider ऑब्जेक्ट, RemoteViews ऑब्जेक्ट को List<SizeF> में मौजूद हर साइज़ से मैप करते हैं. इसलिए, MAX_INIT_VIEW_COUNT से ज़्यादा साइज़ न दें.

Android 12 में, डीपीएस में maxResizeWidth और maxResizeHeight एट्रिब्यूट भी जोड़े गए हैं. हमारा सुझाव है कि ऐसा विजेट जो इनमें से कम से कम एक का इस्तेमाल करे विशेषताएं, विशेषताओं के ज़रिए तय किए आकार से ज़्यादा नहीं होती हैं.

अन्य संसाधन

  • Glance रेफ़रंस दस्तावेज़ देखें.