chrome.action

कंपनी का ब्यौरा

उपलब्धता

मेनिफ़ेस्ट

chrome.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);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

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

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

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

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

बैज

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

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

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

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

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

पॉप-अप

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

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

इस्तेमाल के उदाहरण

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

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

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

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

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

चालू होने की स्थिति

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

उदाहरण

नीचे दिए गए उदाहरणों में, एक्सटेंशन में कार्रवाइयों का इस्तेमाल करने के कुछ सामान्य तरीके बताए गए हैं. इस एपीआई को आज़माने के लिए, chrome-extension-सैंपलडेटा स्टोर करने की जगह से, 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
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

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

डिक्लेरेटिव टोन की मदद से कार्रवाइयों को एम्युलेट करें

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

// service-worker.js

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

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

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

chrome.action.disable(
  tabId?: number,
  callback?: function,
)

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

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