ब्यौरा
आपके एक्सटेंशन में कार्रवाइयों को ट्रिगर करने वाले कीबोर्ड शॉर्टकट जोड़ने के लिए, Command API का इस्तेमाल करें. उदाहरण के लिए, ब्राउज़र कार्रवाई को खोलने के लिए कोई कार्रवाई या एक्सटेंशन को कोई निर्देश भेजें.
मेनिफ़ेस्ट
सिद्धांत और इस्तेमाल
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 पर कंट्रोल बटन का इस्तेमाल करने के लिए,
"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.
}
});
}
टाइप
Command
प्रॉपर्टी
-
ब्यौरा
स्ट्रिंग ज़रूरी नहीं
एक्सटेंशन कमांड की जानकारी
-
नाम
स्ट्रिंग ज़रूरी नहीं
एक्सटेंशन कमांड का नाम
-
शॉर्टकट
स्ट्रिंग ज़रूरी नहीं
इस निर्देश के लिए शॉर्टकट चालू है. अगर शॉर्टकट चालू नहीं है, तो इसे खाली छोड़ा जा सकता है.
तरीके
getAll()
chrome.commands.getAll(
callback?: function,
)
इस एक्सटेंशन के लिए रजिस्टर किए गए सभी एक्सटेंशन के निर्देश और उनके शॉर्टकट (अगर चालू हो) दिखाता है. Chrome 110 से पहले के वर्शन में, यह निर्देश _execute_action नहीं दिखाता है.
पैरामीटर
रिटर्न
-
वादा<Command[]>
Chrome 96 के बाद के वर्शनप्रॉमिस, मेनिफ़ेस्ट V3 और इसके बाद के वर्शन में काम करता है. हालांकि, पुराने सिस्टम के साथ काम करने के लिए कॉलबैक दिए जाते हैं. आप एक ही फ़ंक्शन कॉल पर दोनों का इस्तेमाल नहीं कर सकते. प्रॉमिस उसी टाइप के साथ रिज़ॉल्व हो जाती है जिसे कॉलबैक को पास किया जाता है.