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" कुंजियों को शामिल करें.

सिद्धांत और उनका इस्तेमाल

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

आइकॉन

यह आइकॉन आपके एक्सटेंशन के टूलबार पर मुख्य इमेज है. साथ ही, इसे इसमें "default_icon" कुंजी के ज़रिए सेट किया गया है की "action" कुंजी होनी चाहिए. आइकॉन की चौड़ाई और ऊंचाई 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!');

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

इस उदाहरण में दिखाया गया है कि किसी एक्सटेंशन का बैकग्राउंड लॉजिक, (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,
)