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

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> बंडल किया जाता है. इसमें, डीपीएस में उन संभावित साइज़ की सूची होती है जो विकल्प बंडल में विजेट इंस्टेंस ले सकता है. उपलब्ध साइज़ की संख्या, होस्ट के लागू होने के तरीके पर निर्भर करती है. आम तौर पर, होस्ट फ़ोन के लिए दो साइज़ उपलब्ध कराते हैं—पोर्ट्रेट और लैंडस्केप—और फ़ोल्ड किए जा सकने वाले डिवाइसों के लिए चार साइज़.

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

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

अन्य संसाधन

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