ब्यौरा
chrome.events
नेमस्पेस में कुछ सामान्य टाइप शामिल होते हैं, जिनका इस्तेमाल एपीआई डिस्पैच करने वाले इवेंट करते हैं. इससे आपको कुछ दिलचस्प होने पर, इसकी सूचना मिलती है.
Event
एक ऐसा ऑब्जेक्ट है जिसकी मदद से, कुछ मज़ेदार होने पर आपको सूचना दी जाती है. अलार्म बजने पर सूचना पाने के लिए, chrome.alarms.onAlarm
इवेंट का इस्तेमाल करने का एक उदाहरण यहां दिया गया है:
chrome.alarms.onAlarm.addListener(function(alarm) {
appendToLog('alarms.onAlarm --'
+ ' name: ' + alarm.name
+ ' scheduledTime: ' + alarm.scheduledTime);
});
जैसा कि उदाहरण में दिखाया गया है, आपने addListener()
का इस्तेमाल करके सूचना पाने के लिए रजिस्टर किया. addListener()
का आर्ग्युमेंट हमेशा एक ऐसा फ़ंक्शन होता है जिसे इवेंट को हैंडल करने के लिए तय किया जाता है. हालांकि, फ़ंक्शन के पैरामीटर इस बात पर निर्भर करते हैं कि कौनसा इवेंट हैंडल किया जा रहा है. alarms.onAlarm
के लिए दस्तावेज़ जांचे जा रहे हैं,
आपको दिखेगा कि फ़ंक्शन में एक ही पैरामीटर है: एक alarms.Alarm
ऑब्जेक्ट, जिसमें बीते हुए अलार्म के बारे में
जानकारी है.
इवेंट का इस्तेमाल करने वाले एपीआई के उदाहरण: alarms, i18n, identity, रनटाइम. ज़्यादातर chrome एपीआई में ऐसा होता है.
डिक्लेरेटिव इवेंट हैंडलर
डिक्लेरेटिव इवेंट हैंडलर से नियम तय करने की सुविधा मिलती है. इसमें डिक्लेरेटिव टोन और कार्रवाइयों वाले नियम शामिल होते हैं. शर्तों का मूल्यांकन JavaScript इंजन के बजाय ब्राउज़र में किया जाता है, जो राउंडट्रिप के इंतज़ार में लगने वाले समय को कम करता है और बहुत ज़्यादा काम करता है.
उदाहरण के लिए, डिक्लेरेटिव इवेंट हैंडलर का इस्तेमाल घोषणात्मक वेब अनुरोध एपीआई और घोषणात्मक कॉन्टेंट एपीआई में किया जाता है. इस पेज पर, सभी डिक्लेरेटिव इवेंट हैंडलर के खास कॉन्सेप्ट की जानकारी दी गई है.
नियम
सबसे आसान संभावित नियम में एक या ज़्यादा शर्तें और एक या ज़्यादा कार्रवाइयां होती हैं:
var rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
अगर कोई भी शर्त पूरी हो जाती है, तो सभी कार्रवाइयां की जाती हैं.
शर्तों और कार्रवाइयों के अलावा, आप हर नियम को एक आइडेंटिफ़ायर दे सकते हैं. यह पहले से रजिस्टर किए गए नियमों को रजिस्टर करने से जुड़ी प्रक्रिया को आसान बनाता है और नियमों में प्राथमिकता तय करने को प्राथमिकता देता है. प्राथमिकताओं पर तभी विचार किया जाता है, जब नियम एक-दूसरे के साथ विरोधाभासी हों या किसी खास क्रम में लागू किए जाने की ज़रूरत हो. कार्रवाइयों को उनके नियमों की प्राथमिकता के घटते क्रम में किया जाता है.
var rule = {
id: "my rule", // optional, will be generated if not set.
priority: 100, // optional, defaults to 100.
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
इवेंट के ऑब्जेक्ट
इवेंट ऑब्जेक्ट के लिए नियम बनाए जा सकते हैं. ये इवेंट ऑब्जेक्ट, इवेंट होने पर कॉलबैक फ़ंक्शन को कॉल नहीं करते हैं. हालांकि, यह जांच करें कि रजिस्टर किए गए किसी नियम में कम से कम एक शर्त पूरी हुई है या नहीं. साथ ही, इस नियम से जुड़ी कार्रवाइयां एक्ज़ीक्यूट करें. डिक्लेरेटिव एपीआई के साथ काम करने वाले इवेंट ऑब्जेक्ट के तीन तरीके हैं: events.Event.addRules
, events.Event.removeRules
, और
events.Event.getRules
.
नियम जोड़ना
नियम जोड़ने के लिए, इवेंट ऑब्जेक्ट के addRules()
फ़ंक्शन को कॉल करें. यह अपने पहले पैरामीटर के तौर पर, नियम के इंस्टेंस की एक कैटगरी लेता है. साथ ही, यह एक कॉलबैक फ़ंक्शन भी इस्तेमाल करता है जिसे पूरा होने पर कॉल किया जाता है.
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
अगर नियम सही तरीके से डाले गए थे, तो details
पैरामीटर में शामिल किए गए नियमों का कलेक्शन शामिल होता है. ये नियम उसी क्रम में दिखते हैं जैसे पास किए गए rule_list
में होते हैं. इसमें वैकल्पिक पैरामीटर id
और priority
में जनरेट की गई वैल्यू भरी होती हैं. अगर कोई नियम अमान्य है, जैसे कि उसमें कोई अमान्य शर्त या कार्रवाई शामिल है, तो कोई भी नियम नहीं जोड़ा जाता. साथ ही, कॉलबैक फ़ंक्शन को कॉल करने पर runtime.lastError वैरिएबल सेट कर दिया जाता है. rule_list
के हर नियम में ऐसा यूनीक आइडेंटिफ़ायर होना चाहिए जिसका इस्तेमाल फ़िलहाल किसी दूसरे नियम के लिए न किया जा रहा हो या किसी खाली आइडेंटिफ़ायर का इस्तेमाल न किया जा रहा हो.
नियम हटाना
नियमों को हटाने के लिए, removeRules()
फ़ंक्शन को कॉल करें. यह अपने पहले पैरामीटर के तौर पर नियम आइडेंटिफ़ायर की एक वैकल्पिक अरे और दूसरे पैरामीटर के तौर पर कॉलबैक फ़ंक्शन को स्वीकार करता है.
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
अगर rule_ids
, आइडेंटिफ़ायर का कलेक्शन है, तो कलेक्शन में मौजूद आइडेंटिफ़ायर वाले सभी नियम हटा दिए जाते हैं. अगर rule_ids
किसी ऐसे आइडेंटिफ़ायर को दिखाता है जिसकी जानकारी नहीं है, तो इस आइडेंटिफ़ायर को अनदेखा कर दिया जाता है. अगर
rule_ids
undefined
है, तो इस एक्सटेंशन के रजिस्टर किए गए सभी नियम हटा दिए जाते हैं. callback()
फ़ंक्शन को तब कॉल किया जाता है, जब नियमों को हटाया जाता है.
डेटा पाने के नियम
हाल ही में रजिस्टर किए गए नियमों की सूची फिर से पाने के लिए, getRules()
फ़ंक्शन को कॉल करें. यह removeRules
और कॉलबैक फ़ंक्शन जैसे सिमैंटिक वाले नियम आइडेंटिफ़ायर का वैकल्पिक कलेक्शन स्वीकार करता है.
var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});
callback()
फ़ंक्शन को पास किया गया details
पैरामीटर, नियमों की ऐसी कलेक्शन के बारे में बताता है जिसमें भरे गए वैकल्पिक पैरामीटर भी शामिल हैं.
परफ़ॉर्मेंस
बेहतरीन परफ़ॉर्मेंस पाने के लिए, आपको इन दिशा-निर्देशों को ध्यान में रखना चाहिए.
नियमों को एक साथ रजिस्टर और रजिस्ट्रेशन रद्द करना. हर बार रजिस्ट्रेशन या रजिस्ट्रेशन रद्द करने के बाद, Chrome को अंदरूनी डेटा स्ट्रक्चर को अपडेट करने की ज़रूरत होती है. यह अपडेट एक महंगी कार्रवाई है.
इसके बजाय:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
पसंद करें:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
events.UrlFilter में रेगुलर एक्सप्रेशन से मैच करने वाली सबस्ट्रिंग को प्राथमिकता दें. सबस्ट्रिंग के हिसाब से, मैच करने की प्रोसेस बहुत तेज़ होती है.
इसके बजाय:
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {urlMatches: "example.com/[^?]*foo" } });
पसंद करें:
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {hostSuffix: "example.com", pathContains: "foo"} });
अगर एक जैसे काम करने वाले कई नियम हैं, तो नियमों को मर्ज करके एक कर दें. किसी एक शर्त के पूरा होते ही नियम अपनी कार्रवाइयों को ट्रिगर करते हैं. इससे डुप्लीकेट ऐक्शन सेट के लिए, मैच करने की प्रोसेस तेज़ हो जाती है और मेमोरी कम हो जाती है.
इसके बजाय:
var condition1 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } });
var condition2 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' } });
var rule1 = { conditions: [condition1],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
var rule2 = { conditions: [condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
पसंद करें:
var rule = { conditions: [condition1, condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule]);
फ़िल्टर किए गए इवेंट
फ़िल्टर किए गए इवेंट एक ऐसी सुविधा है जिसकी मदद से ऑडियंस, अपनी पसंद के इवेंट के बारे में बता सकती हैं. फ़िल्टर पास न करने वाले इवेंट के लिए, फ़िल्टर का इस्तेमाल करने वाले लिसनर को शुरू नहीं किया जाएगा. इससे, लिसनिंग कोड ज़्यादा जानकारी वाला और बेहतर तरीके से काम करता है. किसी सर्विस वर्कर को ऐसे इवेंट हैंडल करने के लिए जागना नहीं पड़ता, जिनसे उसे कोई फ़र्क़ नहीं पड़ता.
फ़िल्टर किए गए इवेंट का मकसद, मैन्युअल तरीके से फ़िल्टर करने के कोड से ट्रांज़िशन की अनुमति देना है. जैसे:
chrome.webNavigation.onCommitted.addListener(function(e) {
if (hasHostSuffix(e.url, 'google.com') ||
hasHostSuffix(e.url, 'google.com.au')) {
// ...
}
});
इसमें:
chrome.webNavigation.onCommitted.addListener(function(e) {
// ...
}, {url: [{hostSuffix: 'google.com'},
{hostSuffix: 'google.com.au'}]});
इवेंट में, ऐसे खास फ़िल्टर इस्तेमाल किए जा सकते हैं जो उस इवेंट के लिए काम के हों. किसी इवेंट के साथ काम करने वाले फ़िल्टर की सूची, "फ़िल्टर" सेक्शन में उस इवेंट के दस्तावेज़ में दी गई होगी.
जैसा कि ऊपर दिए गए उदाहरण में दिखाया गया है, यूआरएल से मिलते-जुलते यूआरएल को इवेंट फ़िल्टर के ज़रिए इस्तेमाल किया जाता है. हालांकि, इनमें स्कीम और पोर्ट मैचिंग को छोड़कर, events.UrlFilter
के साथ दिखाई जा सकने वाली, यूआरएल के लिए मैच करने की सुविधाएं एक जैसी होती हैं.
टाइप
Event
एक ऐसा ऑब्जेक्ट जो Chrome इवेंट के लिए, लिसनर को जोड़ने और हटाने की अनुमति देता है.
प्रॉपर्टी
-
addListener
void
किसी इवेंट के लिए, इवेंट लिसनर को कॉलबैक रजिस्टर करता है.
addListener
फ़ंक्शन ऐसा दिखता है:(callback: H)=> {...}
-
कॉलबैक
H
कोई इवेंट होने पर कॉल किया जाता है. इस फ़ंक्शन के पैरामीटर, इवेंट के टाइप पर निर्भर करते हैं.
-
-
addRules
void
इवेंट मैनेज करने के लिए नियमों को रजिस्टर करता है.
addRules
फ़ंक्शन ऐसा दिखता है:(rules: Rule<anyany>[],callback?: function)=> {...}
-
getRules
void
रजिस्टर किए गए मौजूदा नियम दिखाता है.
getRules
फ़ंक्शन ऐसा दिखता है:(ruleIdentifiers?: string[],callback: function)=> {...}
-
ruleIdentifiers
स्ट्रिंग[] ज़रूरी नहीं है
अगर कोई अरे पास हो जाता है, तो सिर्फ़ इस कलेक्शन में शामिल आइडेंटिफ़ायर वाले नियम ही दिखते हैं.
-
कॉलबैक
फ़ंक्शन
callback
पैरामीटर ऐसा दिखता है:(rules: Rule<anyany>[])=>void
-
नियम
नियम<anyany>[]
रजिस्टर किए गए नियम, वैकल्पिक पैरामीटर में वैल्यू से भरे जाते हैं.
-
-
-
hasListener
void
hasListener
फ़ंक्शन ऐसा दिखता है:(callback: H)=> {...}
-
कॉलबैक
H
वह व्यक्ति जिसकी रजिस्ट्रेशन स्थिति की जांच की जाएगी.
-
returns
boolean
अगर इवेंट के लिए कॉलबैक रजिस्टर किया गया है, तो वैल्यू 'सही' होगी.
-
-
hasListeners
void
hasListeners
फ़ंक्शन ऐसा दिखता है:()=> {...}
-
returns
boolean
अगर किसी इवेंट को सुनने वाले लोग रजिस्टर हैं, तो वैल्यू 'सही' होगी.
-
-
removeListener
void
किसी इवेंट से, इवेंट लिसनर कॉलबैक का रजिस्ट्रेशन रद्द कर देता है.
removeListener
फ़ंक्शन ऐसा दिखता है:(callback: H)=> {...}
-
कॉलबैक
H
लिसनर का रजिस्ट्रेशन रद्द किया जाएगा.
-
-
removeRules
void
वर्तमान में रजिस्टर किए गए नियमों का रजिस्ट्रेशन रद्द करता है.
removeRules
फ़ंक्शन ऐसा दिखता है:(ruleIdentifiers?: string[],callback?: function)=> {...}
-
ruleIdentifiers
स्ट्रिंग[] ज़रूरी नहीं है
अगर कोई अरे पास हो जाता है, तो सिर्फ़ इस कलेक्शन में शामिल आइडेंटिफ़ायर वाले नियमों का रजिस्ट्रेशन रद्द किया जाता है.
-
कॉलबैक
फ़ंक्शन ज़रूरी नहीं
callback
पैरामीटर ऐसा दिखता है:()=>void
-
Rule
इवेंट मैनेज करने के लिए, निर्देश देने वाले नियम के बारे में जानकारी.
प्रॉपर्टी
-
काम
कोई भी[]
कोई एक शर्त पूरी होने पर ट्रिगर होने वाली कार्रवाइयों की सूची.
-
conditions
कोई भी[]
कार्रवाइयों को ट्रिगर करने वाली शर्तों की सूची.
-
id
स्ट्रिंग ज़रूरी नहीं
इस नियम का रेफ़रंस देने की अनुमति देने वाला वैकल्पिक आइडेंटिफ़ायर.
-
प्राथमिकता
नंबर ज़रूरी नहीं
इस नियम की वैकल्पिक प्राथमिकता. डिफ़ॉल्ट वैल्यू 100 होती है.
-
टैग
स्ट्रिंग[] ज़रूरी नहीं है
टैग का इस्तेमाल, नियमों की व्याख्या और सेट पर कार्रवाई करने के लिए किया जा सकता है.
UrlFilter
अलग-अलग शर्तों के हिसाब से यूआरएल फ़िल्टर करता है. इवेंट फ़िल्टर करना देखें. सभी शर्तें केस-सेंसिटिव (बड़े और छोटे अक्षरों में अंतर) होती हैं.
प्रॉपर्टी
-
cidrBlocks
स्ट्रिंग[] ज़रूरी नहीं है
Chrome 123 के बाद के वर्शनयह तब मैच करता है, जब यूआरएल का होस्ट वाला हिस्सा कोई आईपी पता है और अरे में बताए गए किसी भी सीआईडीआर ब्लॉक में मौजूद है.
-
hostContains
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब यूआरएल के होस्ट नाम में कोई स्ट्रिंग शामिल है. यह जांचने के लिए कि होस्ट नाम के कॉम्पोनेंट में 'foo' प्रीफ़िक्स है या नहीं, HostContains: '.foo' का इस्तेमाल करें. यह 'www.foobar.com' और 'foo.com' से मैच होता है, क्योंकि होस्ट नेम की शुरुआत में इंप्लिसिट डॉट जोड़ दिया जाता है. इसी तरह, HostContains का इस्तेमाल कॉम्पोनेंट सफ़िक्स ('foo.') और कॉम्पोनेंट ('.foo.') से पूरी तरह मैच करने के लिए किया जा सकता है. आखिरी कॉम्पोनेंट के सफ़िक्स और एग्ज़ैक्ट मैच, HostSuffix का इस्तेमाल करके अलग-अलग होने चाहिए. ऐसा इसलिए, क्योंकि होस्ट के नाम के आखिर में इंप्लिसिट डॉट नहीं जोड़ा जाता है.
-
hostEquals
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब यूआरएल का होस्ट नाम किसी तय स्ट्रिंग के बराबर हो.
-
hostPrefix
स्ट्रिंग ज़रूरी नहीं
तब मैच होता है, जब यूआरएल का होस्ट नाम किसी तय स्ट्रिंग से शुरू होता है.
-
hostSuffix
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब यूआरएल का होस्टनेम किसी खास स्ट्रिंग पर खत्म होता है.
-
originAndPathMatches
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब बिना क्वेरी सेगमेंट और फ़्रैगमेंट आइडेंटिफ़ायर वाला यूआरएल, किसी तय किए गए रेगुलर एक्सप्रेशन से मैच करता है. अगर पोर्ट नंबर डिफ़ॉल्ट पोर्ट नंबर से मेल खाते हैं, तो उन्हें यूआरएल से हटा दिया जाता है. रेगुलर एक्सप्रेशन, RE2 सिंटैक्स का इस्तेमाल करते हैं.
-
pathContains
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब यूआरएल के पाथ सेगमेंट में कोई स्ट्रिंग शामिल हो.
-
pathEquals
स्ट्रिंग ज़रूरी नहीं
तब मैच होता है, जब यूआरएल का पाथ सेगमेंट, किसी खास स्ट्रिंग के बराबर हो.
-
pathPrefix
स्ट्रिंग ज़रूरी नहीं
तब मैच होता है, जब यूआरएल का पाथ सेगमेंट, किसी तय स्ट्रिंग से शुरू होता है.
-
pathSuffix
स्ट्रिंग ज़रूरी नहीं
तब मैच होता है, जब यूआरएल का पाथ सेगमेंट, किसी तय स्ट्रिंग पर खत्म होता है.
-
ports
(number|number[])[] ज़रूरी नहीं
तब मैच करता है, जब यूआरएल का पोर्ट, बताई गई किसी भी पोर्ट सूची में शामिल हो. उदाहरण के लिए,
[80, 443, [1000, 1200]]
, पोर्ट 80, 443, और 1000 से 1200 की रेंज में आने वाले सभी अनुरोधों से मेल खाता है. -
queryContains
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब यूआरएल के क्वेरी सेगमेंट में कोई स्ट्रिंग मौजूद होती है.
-
queryEquals
स्ट्रिंग ज़रूरी नहीं
तब मैच करता है, जब यूआरएल का क्वेरी सेगमेंट किसी तय स्ट्रिंग के बराबर हो.
-
queryPrefix
स्ट्रिंग ज़रूरी नहीं
तब मैच होता है, जब यूआरएल का क्वेरी सेगमेंट किसी तय स्ट्रिंग से शुरू होता है.
-
querySuffix
स्ट्रिंग ज़रूरी नहीं
तब मैच करता है, जब यूआरएल का क्वेरी सेगमेंट, किसी बताई गई स्ट्रिंग पर खत्म होता हो.
-
schemes
स्ट्रिंग[] ज़रूरी नहीं है
तब मैच करता है, जब यूआरएल की स्कीम, अरे में बताई गई किसी भी स्कीम के बराबर होती है.
-
urlContains
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब यूआरएल (फ़्रैगमेंट आइडेंटिफ़ायर के बिना) में कोई स्ट्रिंग शामिल होती है. अगर पोर्ट नंबर डिफ़ॉल्ट पोर्ट नंबर से मेल खाते हैं, तो उन्हें यूआरएल से हटा दिया जाता है.
-
urlEquals
स्ट्रिंग ज़रूरी नहीं
तब मैच करता है, जब यूआरएल (फ़्रैगमेंट आइडेंटिफ़ायर के बिना) किसी तय स्ट्रिंग के बराबर होता है. अगर पोर्ट नंबर डिफ़ॉल्ट पोर्ट नंबर से मेल खाते हैं, तो उन्हें यूआरएल से हटा दिया जाता है.
-
urlMatches
स्ट्रिंग ज़रूरी नहीं
यह तब मैच करता है, जब यूआरएल (फ़्रैगमेंट आइडेंटिफ़ायर के बिना) किसी तय रेगुलर एक्सप्रेशन से मैच करता है. अगर पोर्ट नंबर डिफ़ॉल्ट पोर्ट नंबर से मेल खाते हैं, तो उन्हें यूआरएल से हटा दिया जाता है. रेगुलर एक्सप्रेशन, RE2 सिंटैक्स का इस्तेमाल करते हैं.
-
urlPrefix
स्ट्रिंग ज़रूरी नहीं
तब मैच करता है, जब यूआरएल (फ़्रैगमेंट आइडेंटिफ़ायर के बिना) किसी तय स्ट्रिंग से शुरू होता है. अगर पोर्ट नंबर डिफ़ॉल्ट पोर्ट नंबर से मेल खाते हैं, तो उन्हें यूआरएल से हटा दिया जाता है.
-
urlSuffix
स्ट्रिंग ज़रूरी नहीं
तब मैच करता है, जब यूआरएल (फ़्रैगमेंट आइडेंटिफ़ायर के बिना) किसी तय स्ट्रिंग पर खत्म होता है. अगर पोर्ट नंबर डिफ़ॉल्ट पोर्ट नंबर से मेल खाते हैं, तो उन्हें यूआरएल से हटा दिया जाता है.