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), 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:

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

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(): Promise<Command[]>

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