browser.events

ब्यौरा

कॉन्सेप्ट और इस्तेमाल करने का तरीका

Event एक ऐसा ऑब्जेक्ट होता है जो आपको किसी दिलचस्प घटना के बारे में सूचना देता है. अलार्म बंद होने पर सूचना पाने के लिए, browser.alarms.onAlarm इवेंट का इस्तेमाल करने का उदाहरण यहां दिया गया है:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

उदाहरण में दिखाया गया है कि addListener() का इस्तेमाल करके, सूचना पाने के लिए रजिस्टर किया जाता है. addListener() के लिए आर्ग्युमेंट हमेशा एक ऐसा फ़ंक्शन होता है जिसे आपने इवेंट को हैंडल करने के लिए तय किया है. हालांकि, फ़ंक्शन के पैरामीटर इस बात पर निर्भर करते हैं कि आपको कौनसे इवेंट को हैंडल करना है. alarms.onAlarm के दस्तावेज़ में जाकर, यह देखा जा सकता है कि इस फ़ंक्शन में सिर्फ़ एक पैरामीटर होता है: एक alarms.Alarm ऑब्जेक्ट, जिसमें अलार्म के बारे में जानकारी होती है.

इवेंट का इस्तेमाल करने वाले एपीआई के उदाहरण: alarms, i18n, identity, runtime. ज़्यादातर Chrome API ऐसा करते हैं.

डिक्लेरेटिव इवेंट हैंडलर

डिक्लेरेटिव इवेंट हैंडलर, डिक्लेरेटिव शर्तों और कार्रवाइयों वाले नियमों को तय करने का तरीका उपलब्ध कराते हैं. शर्तों का आकलन JavaScript इंजन के बजाय ब्राउज़र में किया जाता है. इससे राउंडट्रिप में लगने वाला समय कम हो जाता है और ज़्यादा असरदार तरीके से काम किया जा सकता है.

डिक्लेरेटिव इवेंट हैंडलर का इस्तेमाल, उदाहरण के लिए Declarative Content API में किया जाता है. इस पेज पर, सभी डिक्लेरेटिव इवेंट हैंडलर के बुनियादी सिद्धांतों के बारे में बताया गया है.

नियम

सबसे आसान नियम में एक या उससे ज़्यादा शर्तें और एक या उससे ज़्यादा कार्रवाइयां होती हैं:

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

अगर कोई भी शर्त पूरी होती है, तो सभी कार्रवाइयां पूरी की जाती हैं.

शर्तों और कार्रवाइयों के अलावा, हर नियम को एक आइडेंटिफ़ायर दिया जा सकता है. इससे पहले से रजिस्टर किए गए नियमों को आसानी से अनरजिस्टर किया जा सकता है. साथ ही, नियमों के बीच प्राथमिकता तय करने के लिए, उन्हें प्राथमिकता दी जा सकती है. प्राथमिकताओं पर तब ही विचार किया जाता है, जब नियमों का एक-दूसरे से टकराव होता है या उन्हें किसी खास क्रम में लागू करना होता है. कार्रवाइयां, नियमों की प्राथमिकता के घटते क्रम में लागू की जाती हैं.

const 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() फ़ंक्शन को कॉल करें. यह फ़ंक्शन, नियम के इंस्टेंस की एक ऐरे को पहले पैरामीटर के तौर पर लेता है. साथ ही, यह एक कॉलबैक फ़ंक्शन लेता है, जिसे पूरा होने पर कॉल किया जाता है.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

अगर नियमों को सही तरीके से डाला गया है, तो details पैरामीटर में डाले गए नियमों का एक कलेक्शन होता है. ये नियम, पास किए गए rule_list में मौजूद नियमों के क्रम में ही दिखते हैं. साथ ही, id और priority जैसे वैकल्पिक पैरामीटर, जनरेट की गई वैल्यू के साथ भरे जाते हैं. अगर कोई नियम अमान्य है, तो कोई भी नियम नहीं जोड़ा जाता. उदाहरण के लिए, अगर नियम में कोई अमान्य शर्त या कार्रवाई शामिल है, तो ऐसा होता है. साथ ही, जब कॉलबैक फ़ंक्शन को कॉल किया जाता है, तब runtime.lastError वैरिएबल सेट होता है. rule_list में मौजूद हर नियम में एक यूनीक आइडेंटिफ़ायर होना चाहिए. यह आइडेंटिफ़ायर, किसी दूसरे नियम या खाली आइडेंटिफ़ायर के लिए इस्तेमाल नहीं किया गया हो.

नियमों को हटाना

नियमों को हटाने के लिए, removeRules() फ़ंक्शन को कॉल करें. यह नियम के आइडेंटिफ़ायर की एक वैकल्पिक ऐरे को पहले पैरामीटर के तौर पर स्वीकार करता है. साथ ही, कॉलबैक फ़ंक्शन को दूसरे पैरामीटर के तौर पर स्वीकार करता है.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

अगर rule_ids आइडेंटिफ़ायर का एक कलेक्शन है, तो कलेक्शन में शामिल आइडेंटिफ़ायर वाले सभी नियमों को हटा दिया जाता है. अगर rule_ids में कोई ऐसा आइडेंटिफ़ायर शामिल है जिसके बारे में जानकारी नहीं है, तो इस आइडेंटिफ़ायर को अनदेखा कर दिया जाता है. अगर rule_ids को undefined पर सेट किया जाता है, तो इस एक्सटेंशन के सभी रजिस्टर किए गए नियम हटा दिए जाते हैं. नियमों को हटाए जाने पर, callback() फ़ंक्शन को कॉल किया जाता है.

नियम वापस पाना

रजिस्टर किए गए नियमों की सूची पाने के लिए, getRules() फ़ंक्शन को कॉल करें. यह removeRules() के जैसे ही सिमैंटिक वाले नियम आइडेंटिफ़ायर के एक वैकल्पिक कलेक्शन और कॉलबैक फ़ंक्शन को स्वीकार करता है.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

callback() फ़ंक्शन को पास किया गया details पैरामीटर, नियमों की एक ऐसी श्रेणी को दिखाता है जिसमें भरे गए वैकल्पिक पैरामीटर शामिल होते हैं.

परफ़ॉर्मेंस

बेहतरीन परफ़ॉर्मेंस पाने के लिए, आपको इन दिशा-निर्देशों का ध्यान रखना चाहिए.

एक साथ कई नियमों को रजिस्टर और अनरजिस्टर करें. हर रजिस्ट्रेशन या अनरजिस्ट्रेशन के बाद, Chrome को इंटरनल डेटा स्ट्रक्चर अपडेट करने होते हैं. इस अपडेट में ज़्यादा समय लगता है.

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

events.UrlFilter में, रेगुलर एक्सप्रेशन के बजाय सबस्ट्रिंग मैचिंग का इस्तेमाल करें. सबस्ट्रिंग के आधार पर मैचिंग बहुत तेज़ी से होती है.

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

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

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

फ़िल्टर किए गए इवेंट

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

फ़िल्टर किए गए इवेंट, मैन्युअल फ़िल्टरिंग कोड से ट्रांज़िशन करने के लिए होते हैं.

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

इवेंट में ऐसे फ़िल्टर इस्तेमाल किए जा सकते हैं जो उस इवेंट के लिए काम के हों. किसी इवेंट के साथ काम करने वाले फ़िल्टर की सूची, उस इवेंट के दस्तावेज़ में "फ़िल्टर" सेक्शन में दी जाएगी.

मिलते-जुलते यूआरएल (ऊपर दिए गए उदाहरण की तरह) के लिए, इवेंट फ़िल्टर में यूआरएल मैच करने की वही सुविधाएं होती हैं जो events.UrlFilter के साथ इस्तेमाल की जा सकती हैं. हालांकि, इसमें स्कीम और पोर्ट मैच करने की सुविधा शामिल नहीं होती.