chrome.browserAction

ब्यौरा

ब्राउज़र ऐक्शन का इस्तेमाल करके, Google Chrome के मुख्य टूलबार में आइकॉन जोड़े जा सकते हैं. ये आइकॉन, पता बार की दाईं ओर दिखते हैं. ब्राउज़र ऐक्शन में आइकॉन के अलावा, टूलटिप, बैज, और पॉप-अप भी हो सकता है.

उपलब्धता

≤ MV2

नीचे दी गई इमेज में, पता बार की दाईं ओर मौजूद अलग-अलग रंगों वाला स्क्वेयर, ब्राउज़र ऐक्शन का आइकॉन है. आइकॉन के नीचे एक पॉप-अप मौजूद है.

अगर आपको ऐसा आइकॉन बनाना है जो हमेशा चालू नहीं रहता है, तो ब्राउज़र ऐक्शन के बजाय पेज ऐक्शन का इस्तेमाल करें.

मेनिफ़ेस्ट

अपने ब्राउज़र ऐक्शन को एक्सटेंशन मेनिफ़ेस्ट में इस तरह रजिस्टर करें:

{   "name": "My extension",   ...   "browser_action": {     "default_icon": {                // optional       "16": "images/icon16.png",     // optional       "24": "images/icon24.png",     // optional       "32": "images/icon32.png"      // optional     },     "default_title": "Google Mail",  // optional, shown in tooltip     "default_popup": "popup.html"    // optional   },   ... }

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

1.5x या 1.2x जैसे कम इस्तेमाल किए जाने वाले स्केल फ़ैक्टर वाले डिवाइसों का इस्तेमाल अब ज़्यादा होने लगा है. इसलिए, आपको अपने आइकॉन के लिए कई साइज़ उपलब्ध कराने का सुझाव दिया जाता है. इससे यह भी पक्का होता है कि अगर कभी आइकॉन के डिसप्ले का साइज़ बदलता है, तो आपको अलग-अलग आइकॉन देने के लिए कोई और काम नहीं करना पड़ेगा!

डिफ़ॉल्ट आइकॉन रजिस्टर करने के लिए, अब भी पुराने सिंटैक्स का इस्तेमाल किया जा सकता है:

{   "name": "My extension",   ...   "browser_action": {     ...     "default_icon": "images/icon32.png"  // optional     // equivalent to "default_icon": { "32": "images/icon32.png" }   },   ... }

यूज़र इंटरफ़ेस (यूआई) के हिस्से

ब्राउज़र ऐक्शन में आइकॉन, टूलटिप, बैज, और पॉप-अप हो सकता है.

आइकॉन

Chrome में ब्राउज़र ऐक्शन आइकॉन, 16 डिप (डिवाइस से अलग पिक्सल) चौड़े और ऊंचे होते हैं. बड़े आइकॉन को फ़िट होने के लिए रीसाइज़ किया जाता है. हालांकि, सबसे अच्छे नतीजों के लिए, 16 डीपी वाला स्क्वेयर आइकॉन इस्तेमाल करें.

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

स्टैटिक इमेज, WebKit पर दिखने वाले किसी भी फ़ॉर्मैट में हो सकती हैं. जैसे, BMP, GIF, ICO, JPEG या PNG. अनपैक किए गए एक्सटेंशन के लिए, इमेज PNG फ़ॉर्मैट में होनी चाहिए.

आइकॉन सेट करने के लिए, manifest में browser_action के default_icon फ़ील्ड का इस्तेमाल करें या browserAction.setIcon तरीके को कॉल करें.

जब स्क्रीन पिक्सल डेंसिटी (अनुपात size_in_pixel / size_in_dip) 1 से अलग हो, तब आइकॉन को सही तरीके से दिखाने के लिए, आइकॉन को अलग-अलग साइज़ वाली इमेज के सेट के तौर पर तय किया जा सकता है. दिखाने के लिए सही इमेज को सेट से चुना जाएगा, ताकि वह 16 डिप के पिक्सल साइज़ के हिसाब से सबसे सही हो. आइकॉन सेट में, किसी भी साइज़ के आइकॉन स्पेसिफ़िकेशन हो सकते हैं. Chrome सबसे सही आइकॉन को चुनेगा.

टूलटिप

टूलटिप सेट करने के लिए, manifest में browser_action के default_title फ़ील्ड का इस्तेमाल करें या browserAction.setTitle तरीके को कॉल करें. default_title फ़ील्ड के लिए, स्थान-भाषा के हिसाब से स्ट्रिंग तय की जा सकती हैं. ज़्यादा जानकारी के लिए, अंतरराष्ट्रीय स्तर का पेज बनाने का तरीका देखें.

बैज

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

बैज में सीमित जगह होती है. इसलिए, इसमें ज़्यादा से ज़्यादा चार वर्ण होने चाहिए.

browserAction.setBadgeText और browserAction.setBadgeBackgroundColor का इस्तेमाल करके, बैज का टेक्स्ट और रंग सेट करें.

अगर ब्राउज़र ऐक्शन में कोई पॉप-अप होता है, तो उपयोगकर्ता के एक्सटेंशन के आइकॉन पर क्लिक करने पर पॉप-अप दिखता है. पॉप-अप में आपकी पसंद का कोई भी एचटीएमएल कॉन्टेंट शामिल किया जा सकता है. साथ ही, यह कॉन्टेंट के हिसाब से अपने-आप सेट हो जाता है. पॉप-अप 25x25 से छोटा और 800x600 से बड़ा नहीं हो सकता.

अपने ब्राउज़र ऐक्शन में पॉप-अप जोड़ने के लिए, पॉप-अप के कॉन्टेंट वाली एचटीएमएल फ़ाइल बनाएं. manifest में browser_action के default_popup फ़ील्ड में एचटीएमएल फ़ाइल तय करें या browserAction.setPopup तरीके को कॉल करें.

सलाह

सबसे बेहतर विज़ुअल इंपैक्ट के लिए, इन दिशा-निर्देशों का पालन करें:

  • ब्राउज़र ऐक्शन का इस्तेमाल उन सुविधाओं के लिए करें जो ज़्यादातर पेजों पर काम करती हैं.
  • ब्राउज़र ऐक्शन का इस्तेमाल सिर्फ़ उन सुविधाओं के लिए करें जो कुछ पेजों के लिए काम की हों. इसके बजाय, page actions का इस्तेमाल करें.
  • बड़े और रंगीन आइकॉन का इस्तेमाल करें. इससे 16x16-डिप स्पेस का ज़्यादा से ज़्यादा इस्तेमाल किया जा सकेगा. ब्राउज़र ऐक्शन आइकॉन, पेज ऐक्शन आइकॉन से थोड़े बड़े और बोल्ड होने चाहिए.
  • Google Chrome के मोनोक्रोम मेन्यू आइकॉन की नकल न करें. यह थीम के साथ अच्छी तरह से काम नहीं करता है. इसके अलावा, एक्सटेंशन को थोड़ा अलग दिखना चाहिए.
  • करें: अपने आइकॉन में हल्के किनारे जोड़ने के लिए, ऐल्फ़ा पारदर्शिता का इस्तेमाल करें. कई लोग थीम का इस्तेमाल करते हैं. इसलिए, आपका आइकॉन अलग-अलग बैकग्राउंड कलर पर अच्छा दिखना चाहिए.
  • अपने आइकॉन को लगातार ऐनिमेट न करें. यह बहुत परेशान करने वाला है.

उदाहरण

आपको examples/api/browserAction डायरेक्ट्री में, ब्राउज़र ऐक्शन इस्तेमाल करने के आसान उदाहरण मिल सकते हैं. अन्य उदाहरणों और सोर्स कोड देखने में मदद पाने के लिए, सैंपल देखें.

टाइप

TabDetails

Chrome 88 या इसके बाद का वर्शन

प्रॉपर्टी

  • tabId

    number ज़रूरी नहीं

    उस टैब का आईडी जिसके लिए क्वेरी की स्थिति जाननी है. अगर कोई टैब नहीं चुना गया है, तो टैब से जुड़ी नहीं, बल्कि सामान्य स्थिति की जानकारी मिलती है.

तरीके

disable()

प्रॉमिस 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

यह किसी टैब के लिए ब्राउज़र ऐक्शन को बंद करता है.

पैरामीटर

  • tabId

    number ज़रूरी नहीं

    उस टैब का आईडी जिसके लिए ब्राउज़र ऐक्शन में बदलाव करना है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    Chrome 67 या इसके बाद का वर्शन

    callback पैरामीटर ऐसा दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

enable()

प्रॉमिस 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

यह किसी टैब के लिए ब्राउज़र ऐक्शन चालू करता है. यह डिफ़ॉल्ट रूप से चालू होता है.

पैरामीटर

  • tabId

    number ज़रूरी नहीं

    उस टैब का आईडी जिसके लिए ब्राउज़र ऐक्शन में बदलाव करना है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    Chrome 67 या इसके बाद का वर्शन

    callback पैरामीटर ऐसा दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

getBadgeBackgroundColor()

प्रॉमिस 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

इस फ़ंक्शन से, ब्राउज़र ऐक्शन के बैकग्राउंड का रंग मिलता है.

पैरामीटर

  • विवरण

    TabDetails

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर ऐसा दिखता है: 

    (result: ColorArray) => void

रिटर्न

  • Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

getBadgeText()

प्रॉमिस 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

यह ब्राउज़र ऐक्शन के बैज का टेक्स्ट दिखाता है. अगर कोई टैब नहीं चुना जाता है, तो टैब के हिसाब से नहीं, बल्कि सामान्य बैज टेक्स्ट दिखता है.

पैरामीटर

  • विवरण

    TabDetails

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर ऐसा दिखता है: 

    (result: string) => void

    • नतीजा

      स्ट्रिंग

रिटर्न

  • Promise<string>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

getPopup()

प्रॉमिस 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

इस ब्राउज़र ऐक्शन के लिए पॉप-अप के तौर पर सेट किए गए एचटीएमएल दस्तावेज़ को वापस लाता है.

पैरामीटर

  • विवरण

    TabDetails

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर ऐसा दिखता है: 

    (result: string) => void

    • नतीजा

      स्ट्रिंग

रिटर्न

  • Promise<string>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

getTitle()

प्रॉमिस 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

इससे ब्राउज़र ऐक्शन का टाइटल मिलता है.

पैरामीटर

  • विवरण

    TabDetails

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर ऐसा दिखता है: 

    (result: string) => void

    • नतीजा

      स्ट्रिंग

रिटर्न

  • Promise<string>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

setBadgeBackgroundColor()

प्रॉमिस 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

इस विकल्प से, बैज के बैकग्राउंड का रंग सेट किया जाता है.

पैरामीटर

  • विवरण

    ऑब्जेक्ट

    • रंग

      string | ColorArray

      यह 0 से 255 के बीच के चार पूर्णांकों का एक कलेक्शन होता है. इससे बैज का आरजीबीए रंग बनता है. यह सीएसएस हेक्स कलर वैल्यू वाली स्ट्रिंग भी हो सकती है. उदाहरण के लिए, #FF0000 या #F00 (लाल). इससे रंग पूरी तरह से अपारदर्शी हो जाते हैं.

    • tabId

      number ज़रूरी नहीं

      इससे बदलाव सिर्फ़ तब लागू होता है, जब कोई टैब चुना जाता है. टैब बंद होने पर, यह कुकी अपने-आप रीसेट हो जाती है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    Chrome 67 या इसके बाद का वर्शन

    callback पैरामीटर ऐसा दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

setBadgeText()

प्रॉमिस 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

इस विकल्प से, ब्राउज़र ऐक्शन के लिए बैज टेक्स्ट सेट किया जाता है. बैज, आइकॉन के ऊपर दिखता है.

पैरामीटर

  • विवरण

    ऑब्जेक्ट

    • tabId

      number ज़रूरी नहीं

      इससे बदलाव सिर्फ़ तब लागू होता है, जब कोई टैब चुना जाता है. टैब बंद होने पर, यह कुकी अपने-आप रीसेट हो जाती है.

    • टेक्स्ट

      string ज़रूरी नहीं है

      इसमें कितने भी वर्ण पास किए जा सकते हैं. हालांकि, इसमें सिर्फ़ चार वर्ण दिखते हैं. अगर कोई खाली स्ट्रिंग ('') पास की जाती है, तो बैज का टेक्स्ट मिट जाता है. अगर tabId तय किया गया है और text शून्य है, तो तय किए गए टैब का टेक्स्ट मिटा दिया जाता है. साथ ही, डिफ़ॉल्ट रूप से ग्लोबल बैज का टेक्स्ट सेट हो जाता है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    Chrome 67 या इसके बाद का वर्शन

    callback पैरामीटर ऐसा दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

setIcon()

प्रॉमिस 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

इस विकल्प से, ब्राउज़र ऐक्शन के लिए आइकॉन सेट किया जाता है. आइकॉन को इमेज फ़ाइल के पाथ, कैनवस एलिमेंट के पिक्सल डेटा या इनमें से किसी एक के डिक्शनरी के तौर पर सेट किया जा सकता है. path या imageData प्रॉपर्टी में से किसी एक की जानकारी देना ज़रूरी है.

पैरामीटर

  • विवरण

    ऑब्जेक्ट

    • imageData

      ImageData | object वैकल्पिक

      ImageData ऑब्जेक्ट या {size -> ImageData} डिक्शनरी में से कोई एक. यह डिक्शनरी, सेट किए जाने वाले आइकॉन को दिखाती है. अगर आइकॉन को डिक्शनरी के तौर पर तय किया गया है, तो इस्तेमाल की गई इमेज को स्क्रीन की पिक्सल डेंसिटी के हिसाब से चुना जाता है. अगर स्क्रीन स्पेस की एक यूनिट में फ़िट होने वाले इमेज पिक्सल की संख्या scale के बराबर है, तो scale * n साइज़ वाली इमेज चुनी जाती है. यहां n, यूज़र इंटरफ़ेस (यूआई) में आइकॉन का साइज़ है. कम से कम एक इमेज के बारे में बताना ज़रूरी है. ध्यान दें कि 'details.imageData = foo', 'details.imageData = {'16': foo}' के बराबर है

    • पाथ

      string | object ज़रूरी नहीं

      सेट किए जाने वाले आइकॉन की ओर ले जाने वाला कोई मिलता-जुलता इमेज पाथ या {size -> relative image path} डिक्शनरी. अगर आइकॉन को डिक्शनरी के तौर पर तय किया गया है, तो इस्तेमाल की गई इमेज को स्क्रीन की पिक्सल डेंसिटी के हिसाब से चुना जाता है. अगर स्क्रीन स्पेस की एक यूनिट में फ़िट होने वाले इमेज पिक्सल की संख्या scale के बराबर है, तो scale * n साइज़ वाली इमेज चुनी जाती है. यहां n, यूज़र इंटरफ़ेस (यूआई) में आइकॉन का साइज़ है. कम से कम एक इमेज के बारे में बताना ज़रूरी है. ध्यान दें कि 'details.path = foo' का मतलब 'details.path = {'16': foo}' है

    • tabId

      number ज़रूरी नहीं

      इससे बदलाव सिर्फ़ तब लागू होता है, जब कोई टैब चुना जाता है. टैब बंद होने पर, यह कुकी अपने-आप रीसेट हो जाती है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    callback पैरामीटर ऐसा दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 116 और इसके बाद के वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

setPopup()

प्रॉमिस 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

यह विकल्प, एचटीएमएल दस्तावेज़ को सेट करता है. इससे उपयोगकर्ता के ब्राउज़र ऐक्शन आइकॉन पर क्लिक करने पर, एचटीएमएल दस्तावेज़ पॉप-अप के तौर पर खुलता है.

पैरामीटर

  • विवरण

    ऑब्जेक्ट

    • पॉप-अप

      स्ट्रिंग

      पॉप-अप में दिखाने के लिए, एचटीएमएल फ़ाइल का रिलेटिव पाथ. अगर इसे खाली स्ट्रिंग ('') पर सेट किया जाता है, तो कोई पॉप-अप नहीं दिखता है.

    • tabId

      number ज़रूरी नहीं

      इससे बदलाव सिर्फ़ तब लागू होता है, जब कोई टैब चुना जाता है. टैब बंद होने पर, यह कुकी अपने-आप रीसेट हो जाती है.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    Chrome 67 या इसके बाद का वर्शन

    callback पैरामीटर ऐसा दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

setTitle()

प्रॉमिस 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

इस विकल्प से, ब्राउज़र ऐक्शन का टाइटल सेट किया जाता है. यह टाइटल टूलटिप में दिखता है.

पैरामीटर

  • विवरण

    ऑब्जेक्ट

    • tabId

      number ज़रूरी नहीं

      इससे बदलाव सिर्फ़ तब लागू होता है, जब कोई टैब चुना जाता है. टैब बंद होने पर, यह कुकी अपने-आप रीसेट हो जाती है.

    • title

      स्ट्रिंग

      माउस घुमाने पर, ब्राउज़र ऐक्शन को यह स्ट्रिंग दिखानी चाहिए.

  • कॉलबैक

    फ़ंक्शन ज़रूरी नहीं

    Chrome 67 या इसके बाद का वर्शन

    callback पैरामीटर ऐसा दिखता है: 

    () => void

रिटर्न

  • Promise<void>

    Chrome 88 या इसके बाद का वर्शन

    प्रॉमिस सिर्फ़ मेनिफ़ेस्ट V3 और इसके बाद के वर्शन के लिए काम करते हैं. अन्य प्लैटफ़ॉर्म को कॉलबैक का इस्तेमाल करना होगा.

इवेंट

onClicked

chrome.browserAction.onClicked.addListener(
  callback: function,
)

यह इवेंट तब ट्रिगर होता है, जब ब्राउज़र ऐक्शन आइकॉन पर क्लिक किया जाता है. अगर ब्राउज़र ऐक्शन में पॉप-अप है, तो यह इवेंट ट्रिगर नहीं होता.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर ऐसा दिखता है: 

    (tab: tabs.Tab) => void