browser.action

ब्यौरा

उपलब्धता

मेनिफ़ेस्ट

browser.action API का इस्तेमाल करने के लिए, 3 का "manifest_version" तय करें. साथ ही, अपनी मेनिफ़ेस्ट फ़ाइल में "action" कुंजी शामिल करें.

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

"action" कुंजी (और इसके चाइल्ड) का इस्तेमाल करना ज़रूरी नहीं है. इसे शामिल न करने पर भी, एक्सटेंशन को टूलबार में दिखाया जाता है, ताकि एक्सटेंशन के मेन्यू को ऐक्सेस किया जा सके. इसलिए, हमारा सुझाव है कि आप हमेशा कम से कम "action" और "default_icon" कुंजियां शामिल करें.

कॉन्सेप्ट और इस्तेमाल करने का तरीका

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

आइकॉन

यह आइकॉन, आपके एक्सटेंशन के टूलबार पर मौजूद मुख्य इमेज होती है. इसे आपके मेनिफ़ेस्ट की "action" कुंजी में मौजूद "default_icon" कुंजी से सेट किया जाता है. आइकॉन की चौड़ाई और लंबाई 16 डिवाइस-इंडिपेंडेंट पिक्सल (डीआईपी) होनी चाहिए.

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

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

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

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

पैक्ड एक्सटेंशन (जो .crx फ़ाइल से इंस्टॉल किए जाते हैं) के लिए, इमेज ऐसे ज़्यादातर फ़ॉर्मैट में हो सकती हैं जिन्हें Blink रेंडरिंग इंजन दिखा सकता है. इनमें PNG, JPEG, BMP, ICO वगैरह शामिल हैं. SVG फ़ाइल फ़ॉर्मैट इस्तेमाल नहीं किया जा सकता. अनपैक किए गए एक्सटेंशन में, PNG इमेज का इस्तेमाल करना ज़रूरी है.

टूलटिप (टाइटल)

जब उपयोगकर्ता टूलबार में एक्सटेंशन के आइकॉन पर माउस पॉइंटर को घुमाता है, तब टूलटिप या टाइटल दिखता है. जब बटन पर फ़ोकस किया जाता है, तब स्क्रीन रीडर इस टेक्स्ट को भी पढ़ता है.

डिफ़ॉल्ट टूलटिप को manifest.json में मौजूद "action" कुंजी के "default_title" फ़ील्ड का इस्तेमाल करके सेट किया जाता है. action.setTitle() को कॉल करके, इसे प्रोग्राम के हिसाब से भी सेट किया जा सकता है.

बैज

कार्रवाइयों में, "बैज" दिखाने का विकल्प होता है. यह आइकॉन के ऊपर लेयर किया गया थोड़ा सा टेक्स्ट होता है. इस सुविधा की मदद से, एक्सटेंशन की स्थिति के बारे में थोड़ी जानकारी दिखाने के लिए, कार्रवाई को अपडेट किया जा सकता है. जैसे, काउंटर. बैज में एक टेक्स्ट कॉम्पोनेंट और बैकग्राउंड का रंग होता है. जगह सीमित होने की वजह से, हमारा सुझाव है कि बैज के टेक्स्ट में चार या इससे कम वर्णों का इस्तेमाल करें.

बैज बनाने के लिए, इसे प्रोग्राम के हिसाब से सेट करें. इसके लिए, action.setBadgeBackgroundColor() और action.setBadgeText() को कॉल करें. मेनिफ़ेस्ट में, बैज की डिफ़ॉल्ट सेटिंग मौजूद नहीं है. बैज के रंग की वैल्यू, 0 से 255 के बीच के चार पूर्णांकों का एक ऐसा कलेक्शन हो सकता है जो बैज के आरजीबीए रंग को बनाता है. इसके अलावा, यह सीएसएस रंग की वैल्यू वाली स्ट्रिंग भी हो सकती है.

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

पॉप-अप

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

पॉप-अप को शुरू में manifest.json फ़ाइल में मौजूद "action" कुंजी में "default_popup" प्रॉपर्टी के ज़रिए सेट किया जाता है. अगर यह प्रॉपर्टी मौजूद है, तो इसे एक्सटेंशन डायरेक्ट्री में मौजूद किसी रिलेटिव पाथ की ओर ले जाना चाहिए. action.setPopup() तरीके का इस्तेमाल करके, इसे डाइनैमिक तौर पर भी अपडेट किया जा सकता है, ताकि यह किसी दूसरे रिलेटिव पाथ की ओर इशारा करे.

उपयोग के उदाहरण

हर टैब की स्थिति

एक्सटेंशन ऐक्शन की स्थिति, हर टैब के लिए अलग-अलग हो सकती है. किसी टैब के लिए वैल्यू सेट करने के लिए, action API के सेटिंग के तरीकों में tabId प्रॉपर्टी का इस्तेमाल करें. उदाहरण के लिए, किसी टैब के लिए बैज का टेक्स्ट सेट करने के लिए, कुछ ऐसा करें:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

browser.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

अगर tabId प्रॉपर्टी को शामिल नहीं किया जाता है, तो सेटिंग को ग्लोबल सेटिंग माना जाता है. टैब के हिसाब से की गई सेटिंग को ग्लोबल सेटिंग से ज़्यादा प्राथमिकता दी जाती है.

चालू की गई स्थिति

डिफ़ॉल्ट रूप से, टूलबार में मौजूद कार्रवाइयां हर टैब पर चालू होती हैं. इसका मतलब है कि उन पर क्लिक किया जा सकता है. मेनिफ़ेस्ट की action कुंजी में default_state प्रॉपर्टी सेट करके, इस डिफ़ॉल्ट सेटिंग को बदला जा सकता है. अगर default_state को "disabled" पर सेट किया जाता है, तो कार्रवाई डिफ़ॉल्ट रूप से बंद हो जाती है. इस पर क्लिक करने की सुविधा को प्रोग्राम के हिसाब से चालू करना होगा. अगर default_state को "enabled" (डिफ़ॉल्ट) पर सेट किया जाता है, तो कार्रवाई डिफ़ॉल्ट रूप से चालू होती है और इस पर क्लिक किया जा सकता है.

action.enable() और action.disable() तरीकों का इस्तेमाल करके, प्रोग्राम के हिसाब से स्थिति को कंट्रोल किया जा सकता है. इससे सिर्फ़ यह तय होता है कि आपके एक्सटेंशन को पॉप-अप (अगर कोई हो) या action.onClicked इवेंट भेजा जाएगा या नहीं. इससे टूलबार में कार्रवाई की मौजूदगी पर कोई असर नहीं पड़ता.

उदाहरण

यहां कुछ सामान्य उदाहरण दिए गए हैं, जिनसे पता चलता है कि एक्सटेंशन में कार्रवाइयों का इस्तेमाल कैसे किया जाता है. इस एपीआई को आज़माने के लिए, chrome-extension-samples रिपॉज़िटरी से Action API का उदाहरण इंस्टॉल करें.

पॉप-अप दिखाएं

आम तौर पर, जब उपयोगकर्ता एक्सटेंशन की कार्रवाई पर क्लिक करता है, तो एक्सटेंशन एक पॉप-अप दिखाता है. अपने एक्सटेंशन में इस सुविधा को लागू करने के लिए, manifest.json में पॉप-अप का एलान करें. साथ ही, वह कॉन्टेंट तय करें जिसे Chrome को पॉप-अप में दिखाना चाहिए.

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

क्लिक करने पर कॉन्टेंट स्क्रिप्ट इंजेक्ट करना

एक्सटेंशन के लिए, एक्सटेंशन की कार्रवाई का इस्तेमाल करके अपनी मुख्य सुविधा को दिखाना एक सामान्य पैटर्न है. नीचे दिए गए उदाहरण में इस पैटर्न के बारे में बताया गया है. जब उपयोगकर्ता इस कार्रवाई पर क्लिक करता है, तो एक्सटेंशन मौजूदा पेज में कॉन्टेंट स्क्रिप्ट डालता है. इसके बाद, कॉन्टेंट स्क्रिप्ट एक सूचना दिखाती है. इससे यह पुष्टि की जाती है कि सब कुछ ठीक से काम कर रहा है.

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
browser.action.onClicked.addListener((tab) => {
  browser.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

declarativeContent की मदद से कार्रवाइयों को दोहराना

इस उदाहरण में दिखाया गया है कि एक्सटेंशन का बैकग्राउंड लॉजिक, (a) डिफ़ॉल्ट रूप से किसी कार्रवाई को कैसे बंद कर सकता है और (b) कुछ खास साइटों पर कार्रवाई को चालू करने के लिए, declarativeContent का इस्तेमाल कैसे कर सकता है.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

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

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)