browser.commands

ब्यौरा

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

मेनिफ़ेस्ट

इस एपीआई का इस्तेमाल करने के लिए, मेनिफ़ेस्ट में इन कुंजियों का एलान करना ज़रूरी है.

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

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

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

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

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

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

  • 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:

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

कार्रवाई से जुड़े निर्देश

_execute_action (Manifest V3), _execute_browser_action (Manifest V2), और _execute_page_action (Manifest 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:

browser.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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

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

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

service-worker.js:

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

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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.
    }
  });
}

टाइप

Command

प्रॉपर्टी

  • ब्यौरा

    string ज़रूरी नहीं

    एक्सटेंशन कमांड का ब्यौरा

  • नाम

    string ज़रूरी नहीं

    एक्सटेंशन कमांड का नाम

  • शॉर्टकट

    string ज़रूरी नहीं

    इस निर्देश के लिए चालू शॉर्टकट. अगर कोई शॉर्टकट चालू नहीं है, तो यह खाली रहेगा.

तरीके

getAll()

browser.commands.getAll(): Promise<Command[]>

यह इस एक्सटेंशन के लिए रजिस्टर किए गए सभी एक्सटेंशन कमांड और उनके शॉर्टकट (अगर चालू हैं) दिखाता है. Chrome 110 से पहले के वर्शन में, यह कमांड _execute_action नहीं दिखाता था.

रिटर्न

  • Promise<Command[]>

    Chrome 96+ Chrome 148 से browser.*

    यह रजिस्टर किए गए निर्देशों की सूची के साथ रिज़ॉल्व हो जाता है.

इवेंट

onCommand

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

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

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर कुछ ऐसा दिखता है: 

    (command: string, tab?: tabs.Tab) => void

    • निर्देश

      स्ट्रिंग

    • टैब

      tabs.Tab ज़रूरी नहीं