chrome.events

refresh date: 2026-09-25 robots: noindex

ब्यौरा

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 ऑब्जेक्ट, जिसमें अलार्म के बंद होने की जानकारी होती है.

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

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

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

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

नियम

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

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]);

prefer:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

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

इसके बजाय:

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

prefer:

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]);

prefer:

  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 के साथ इस्तेमाल की जा सकती हैं. हालांकि, इसमें स्कीम और पोर्ट मैच करने की सुविधा शामिल नहीं होती.