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() को भी कॉल किया जा सकता है. इसके लिए, किसी दूसरी इमेज का पाथ दें या HTML कैनवस एलिमेंट का इस्तेमाल करके, डाइनैमिक तौर पर जनरेट होने वाला आइकॉन दें. इसके अलावा, अगर एक्सटेंशन के सेवा वर्कर से सेट किया जा रहा है, तो ऑफ़स्क्रीन कैनवस एपीआई का इस्तेमाल करें.

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 के बीच के चार पूर्णांकों का ऐरे हो सकती है. यह ऐरे, बैज का आरजीबी रंग बनाता है. इसके अलावा, बैज के रंग की वैल्यू, सीएसएस रंग की वैल्यू वाली स्ट्रिंग भी हो सकती है.

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 पिक्सल के बीच होना चाहिए.

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

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

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

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

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

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

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

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

डिफ़ॉल्ट रूप से, हर टैब पर टूलबार की कार्रवाइयां चालू (क्लिक की जा सकने वाली) होती हैं. इसे कंट्रोल करने के लिए, 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
chrome.action.onClicked.addListener((tab) => {
  chrome.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
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,
)

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