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, Shift, MacCtrl (सिर्फ़ macOS के लिए), Command (सिर्फ़ macOS के लिए), Search (सिर्फ़ ChromeOS के लिए)

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

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

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

  • macOS के कई कीबोर्ड पर, Alt का मतलब Option बटन से है.

  • macOS पर, Ctrl या Alt के बजाय Command या MacCtrl का भी इस्तेमाल किया जा सकता है. इसके लिए, अगला बुलेट पॉइंट देखें.

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

  • Command का इस्तेमाल "mac" शॉर्टकट में भी किया जा सकता है, ताकि 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 (मेनिफ़ेस्ट 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,
)