chrome.commands

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

मेनिफ़ेस्ट

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

Commands API की मदद से, एक्सटेंशन डेवलपर खास निर्देशों को तय कर सकते हैं और उन्हें डिफ़ॉल्ट की-कॉम्बिनेशन से बाइंड कर सकते हैं. एक्सटेंशन के स्वीकार किए जाने वाले हर निर्देश को एक्सटेंशन के मेनिफ़ेस्ट में "commands" ऑब्जेक्ट की प्रॉपर्टी के तौर पर बताया जाना चाहिए.

प्रॉपर्टी कुंजी का इस्तेमाल निर्देश के नाम के तौर पर किया जाता है. कमांड ऑब्जेक्ट दो प्रॉपर्टी ले सकते हैं.

suggested_key

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

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

• ऑब्जेक्ट वैल्यू की मदद से, एक्सटेंशन डेवलपर हर प्लैटफ़ॉर्म के लिए कीबोर्ड शॉर्टकट को पसंद के मुताबिक बना सकता है. प्लैटफ़ॉर्म के हिसाब से शॉर्टकट देते समय, मान्य ऑब्जेक्ट प्रॉपर्टी default, chromeos, linux, mac, और windows होती हैं.

ज़्यादा जानकारी के लिए, मुख्य कॉम्बिनेशन की ज़रूरी शर्तें देखें.

description

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

किसी एक्सटेंशन में कई निर्देश हो सकते हैं, लेकिन वह सुझाए गए ज़्यादा से ज़्यादा चार कीबोर्ड शॉर्टकट के बारे में बता सकता है. उपयोगकर्ता chrome://extensions/shortcuts डायलॉग का इस्तेमाल करके, मैन्युअल तरीके से ज़्यादा शॉर्टकट जोड़ सकता है.

काम करने वाली कुंजियां

ये बटन, इस्तेमाल किए जा सकने वाले कमांड शॉर्टकट हैं. मुख्य परिभाषाएं केस-सेंसिटिव (बड़े और छोटे अक्षरों में अंतर) होती हैं. गलत केस वाली कुंजी के साथ किसी एक्सटेंशन को लोड करने की कोशिश करने से, इंस्टॉलेशन के समय मेनिफ़ेस्ट पार्स गड़बड़ी हो सकती है.

ऐल्फ़ा कुंजियां

A ... Z

अंकों वाली कुंजियां

0 ... 9

स्टैंडर्ड कुंजी स्ट्रिंग

सामान्य–Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

ऐरो बटन–Up, Down, Left, Right

मीडिया कुंजियां–MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

संशोधक कुंजी स्ट्रिंग

Ctrl, Alt (macOS पर Option), Shift, MacCtrl (सिर्फ़ macOS के लिए), Command (सिर्फ़ macOS के लिए), Search (सिर्फ़ ChromeOS पर)

की कॉम्बिनेशन की ज़रूरी शर्तें

• एक्सटेंशन कमांड शॉर्टकट में Ctrl या Alt शामिल होना चाहिए.

  • मीडिया कुंजियों के साथ मॉडिफ़ायर का इस्तेमाल नहीं किया जा सकता.

• macOS पर Ctrl, अपने-आप Command में बदल जाता है.

  • macOS पर Control बटन का इस्तेमाल करने के लिए, "mac" शॉर्टकट तय करते समय Ctrl को MacCtrl से बदलें.

  • MacCtrl को किसी दूसरे प्लैटफ़ॉर्म के लिए एक साथ इस्तेमाल करने पर, पुष्टि करने में गड़बड़ी हो सकती है. साथ ही, एक्सटेंशन इंस्टॉल नहीं हो पाएगा.

• सभी प्लैटफ़ॉर्म पर Shift, कार्रवाई बदलने वाली एक वैकल्पिक वैल्यू है.

• Search एक वैकल्पिक मॉडिफ़ायर है, जो सिर्फ़ ChromeOS के लिए उपलब्ध है.

• कुछ ऑपरेटिंग सिस्टम और Chrome शॉर्टकट (जैसे कि विंडो मैनेजमेंट) को हमेशा एक्सटेंशन कमांड शॉर्टकट के मुकाबले प्राथमिकता मिलती है. इन्हें बदला नहीं जा सकता.

कमांड इवेंट मैनेज करना

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "run-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Run \"foo\" on the current page."
    },
    "_execute_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    }
  },
  ...
}

आपके सर्विस वर्कर में, onCommand.addListener का इस्तेमाल करके मेनिफ़ेस्ट में तय किए गए हर निर्देश के लिए, हैंडलर को बाइंड किया जा सकता है. उदाहरण के लिए:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

कार्रवाई के निर्देश

_execute_action (Manifest V3), _execute_browser_action (मेनिफ़ेस्ट V2), और _execute_page_action (मेनिफ़ेस्ट V2) निर्देश आपकी कार्रवाई, ब्राउज़र पर की गई कार्रवाई या पेज पर की गई कार्रवाई को ट्रिगर करने के लिए रिज़र्व हैं. ये निर्देश, स्टैंडर्ड निर्देशों की तरह command.onCommand इवेंट नहीं भेजते.

अगर आपको अपने पॉप-अप खुलने के बाद कोई कार्रवाई करनी है, तो अपने पॉप-अप की JavaScript में DOMContentLoaded इवेंट सुनें.

स्कोप

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

ग्लोबल कमांड के लिए कीबोर्ड शॉर्टकट के सुझाव, Ctrl+Shift+[0..9] तक ही सीमित हैं. यह दूसरे ऐप्लिकेशन में शॉर्टकट को बदलने के जोखिम को कम करने का एक सुरक्षा उपाय है. अगर, उदाहरण के लिए, Alt+P को ग्लोबल लेवल के तौर पर अनुमति दी जाती है, तो प्रिंट डायलॉग खोलने के लिए कीबोर्ड शॉर्टकट शायद दूसरे ऐप्लिकेशन में काम न करे.

असली उपयोगकर्ता, chrome://extensions/shortcuts पर दिखाए गए यूज़र इंटरफ़ेस (यूआई) का इस्तेमाल करके, ग्लोबल कमांड को अपने पसंदीदा की कॉम्बिनेशन पर फिर से मैप कर सकते हैं.

उदाहरण:

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

उदाहरण

नीचे दिए गए उदाहरण, Commands API के मुख्य फ़ंक्शन में बदलाव करते हैं.

बुनियादी निर्देश

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

manifest.json:

{
  "name": "Command demo - basic",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "commands": {
    "inject-script": {
      "suggested_key": "Ctrl+Shift+Y",
      "description": "Inject a script on the page"
    }
  }
}

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

कार्रवाई के लिए निर्देश

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

manifest.json:

{
  "name": "Commands demo - action invocation",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "permissions": ["activeTab", "scripting"],
  "action": {},
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+U",
        "mac": "Command+U"
      }
    }
  }
}

service-worker.js:

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    func: contentScriptFunc,
    args: ['action'],
  });
});

function contentScriptFunc(name) {
  alert(`"${name}" executed`);
}

// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

रजिस्टर किए गए निर्देशों की पुष्टि करें

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

service-worker.js:

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  chrome.commands.getAll((commands) => {
    let missingShortcuts = [];

    for (let {name, shortcut} of commands) {
      if (shortcut === '') {
        missingShortcuts.push(name);
      }
    }

    if (missingShortcuts.length > 0) {
      // Update the extension UI to inform the user that one or more
      // commands are currently unassigned.
    }
  });
}

chrome.commands.getAll(
  callback?: function,
)

chrome.commands.onCommand.addListener(
  callback: function,
)