chrome.events

refresh date: 2026-09-25 robots: noindex

ब्यौरा

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, runtime. ज़्यादातर 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]);

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

टाइप

Event

यह एक ऐसा ऑब्जेक्ट है जिसकी मदद से, Chrome इवेंट के लिए लिसनर जोड़े और हटाए जा सकते हैं.

प्रॉपर्टी

  • addListener

    void

    किसी इवेंट के लिए, इवेंट लिसनर कॉलबैक को रजिस्टर करता है.

    addListener फ़ंक्शन इस तरह दिखता है: 

    (callback: H) => {...}

    • कॉलबैक

      H

      कोई इवेंट होने पर कॉल किया जाता है. इस फ़ंक्शन के पैरामीटर, इवेंट के टाइप पर निर्भर करते हैं.

  • addRules

    void

    इवेंट मैनेज करने के लिए नियम रजिस्टर करता है.

    addRules फ़ंक्शन इस तरह दिखता है: 

    (rules: Rule<anyany>[], callback?: function) => {...}

    • नियम

      Rule<anyany>[]

      रजिस्टर किए जाने वाले नियम. ये पहले से रजिस्टर किए गए नियमों की जगह नहीं लेते.

    • कॉलबैक

      function ज़रूरी नहीं

      callback पैरामीटर कुछ ऐसा दिखता है: 

      (rules: Rule<anyany>[]) => void

      • नियम

        Rule<anyany>[]

        रजिस्टर किए गए नियमों के लिए, वैकल्पिक पैरामीटर में वैल्यू भरी जाती हैं.

  • getRules

    void

    यह फ़िलहाल रजिस्टर किए गए नियम दिखाता है.

    getRules फ़ंक्शन इस तरह दिखता है: 

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

      string[] ज़रूरी नहीं

      अगर कोई कलेक्शन पास किया जाता है, तो सिर्फ़ इस कलेक्शन में मौजूद आइडेंटिफ़ायर वाले नियम दिखाए जाते हैं.

    • कॉलबैक

      फ़ंक्शन

      callback पैरामीटर कुछ ऐसा दिखता है: 

      (rules: Rule<anyany>[]) => void

      • नियम

        Rule<anyany>[]

        रजिस्टर किए गए नियमों के लिए, वैकल्पिक पैरामीटर में वैल्यू भरी जाती हैं.

  • hasListener

    void

    hasListener फ़ंक्शन इस तरह दिखता है: 

    (callback: H) => {...}

    • कॉलबैक

      H

      वह लिसनर जिसके रजिस्ट्रेशन के स्टेटस की जांच की जाएगी.

    • returns

      बूलियन

      अगर इवेंट के लिए कॉलबैक रजिस्टर किया गया है, तो True.

  • hasListeners

    void

    hasListeners फ़ंक्शन इस तरह दिखता है: 

    () => {...}

    • returns

      बूलियन

      अगर इवेंट के लिए कोई इवेंट लिसनर रजिस्टर किया गया है, तो True.

  • removeListener

    void

    किसी इवेंट से इवेंट लिसनर कॉलबैक को अनरजिस्टर करता है.

    removeListener फ़ंक्शन इस तरह दिखता है: 

    (callback: H) => {...}

    • कॉलबैक

      H

      वह लिसनर जिसका रजिस्ट्रेशन रद्द किया जाएगा.

  • removeRules

    void

    फ़िलहाल रजिस्टर किए गए नियमों का रजिस्ट्रेशन रद्द करता है.

    removeRules फ़ंक्शन इस तरह दिखता है: 

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • ruleIdentifiers

      string[] ज़रूरी नहीं

      अगर कोई कलेक्शन पास किया जाता है, तो सिर्फ़ इस कलेक्शन में मौजूद आइडेंटिफ़ायर वाले नियमों का रजिस्ट्रेशन रद्द किया जाता है.

    • कॉलबैक

      function ज़रूरी नहीं

      callback पैरामीटर कुछ ऐसा दिखता है: 

      () => void

Rule

इवेंट मैनेज करने के लिए, डिक्लेरेटिव नियम की जानकारी.

प्रॉपर्टी

  • कार्रवाइयां

    any[]

    उन कार्रवाइयों की सूची जो इनमें से कोई एक शर्त पूरी होने पर ट्रिगर होती हैं.

  • शर्तें

    any[]

    उन शर्तों की सूची जिनसे कार्रवाइयां ट्रिगर हो सकती हैं.

  • आईडी

    string ज़रूरी नहीं

    यह एक वैकल्पिक आइडेंटिफ़ायर है, जिसकी मदद से इस नियम का रेफ़रंस दिया जा सकता है.

  • प्राथमिकता

    number ज़रूरी नहीं

    इस नियम की प्राथमिकता. इसे सेट करना ज़रूरी नहीं है. डिफ़ॉल्ट वैल्यू 100 होती है.

  • टैग

    string[] ज़रूरी नहीं

    टैग का इस्तेमाल, नियमों के बारे में जानकारी देने और नियमों के सेट पर कार्रवाइयां करने के लिए किया जा सकता है.

UrlFilter

अलग-अलग शर्तों के हिसाब से यूआरएल फ़िल्टर करता है. इवेंट फ़िल्टर करना देखें. सभी शर्तें केस-सेंसिटिव होती हैं.

प्रॉपर्टी

  • cidrBlocks

    string[] ज़रूरी नहीं

    Chrome 123 या इसके बाद का वर्शन

    अगर यूआरएल का होस्ट वाला हिस्सा एक आईपी पता है और वह कलेक्शन में बताए गए किसी भी सीआईडीआर ब्लॉक में शामिल है, तो यह मैच करता है.

  • hostContains

    string ज़रूरी नहीं

    अगर यूआरएल के होस्ट का नाम में कोई स्ट्रिंग शामिल है, तो यह मैच करता है. यह जांचने के लिए कि होस्ट के नाम के कॉम्पोनेंट में प्रीफ़िक्स 'foo' है या नहीं, hostContains: '.foo' का इस्तेमाल करें. यह 'www.foobar.com' और 'foo.com' से मैच करता है, क्योंकि होस्ट के नाम की शुरुआत में एक डॉट जोड़ा जाता है. इसी तरह, hostContains का इस्तेमाल कॉम्पोनेंट के सफ़िक्स ('foo.') से मैच करने और कॉम्पोनेंट ('.foo.') से एग्ज़ैक्ट मैच करने के लिए किया जा सकता है. आखिरी कॉम्पोनेंट के लिए, सफ़िक्स और एग्ज़ैक्ट मैचिंग को hostSuffix का इस्तेमाल करके अलग से करना होगा. ऐसा इसलिए, क्योंकि होस्ट के नाम के आखिर में कोई डॉट नहीं जोड़ा जाता.

  • hostEquals

    string ज़रूरी नहीं

    अगर यूआरएल के होस्ट का नाम, किसी स्ट्रिंग से मैच करता है, तो यह ट्रिगर फ़ायर होता है.

  • hostPrefix

    string ज़रूरी नहीं

    अगर यूआरएल के होस्ट का नाम किसी स्ट्रिंग से शुरू होता है, तो यह मैच करता है.

  • hostSuffix

    string ज़रूरी नहीं

    अगर यूआरएल के होस्ट का नाम, बताई गई स्ट्रिंग से मैच करता है, तो यह शर्त पूरी हो जाती है.

  • originAndPathMatches

    string ज़रूरी नहीं

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

  • pathContains

    string ज़रूरी नहीं

    अगर यूआरएल के पाथ सेगमेंट में कोई स्ट्रिंग मौजूद है, तो यह उससे मैच करता है.

  • pathEquals

    string ज़रूरी नहीं

    अगर यूआरएल का पाथ सेगमेंट, किसी स्ट्रिंग से मैच करता है, तो यह शर्त पूरी हो जाती है.

  • pathPrefix

    string ज़रूरी नहीं

    अगर यूआरएल का पाथ सेगमेंट किसी स्ट्रिंग से शुरू होता है, तो यह मैच करता है.

  • pathSuffix

    string ज़रूरी नहीं

    अगर यूआरएल का पाथ सेगमेंट, किसी तय स्ट्रिंग पर खत्म होता है, तो यह मैच करता है.

  • ports

    (number | number[])[] ज़रूरी नहीं

    अगर यूआरएल का पोर्ट, पोर्ट की बताई गई किसी भी सूची में शामिल है, तो यह मैच करता है. उदाहरण के लिए, [80, 443, [1000, 1200]] पोर्ट 80, 443, और 1000-1200 की रेंज में मौजूद सभी अनुरोधों से मैच करता है.

  • queryContains

    string ज़रूरी नहीं

    अगर यूआरएल के क्वेरी सेगमेंट में कोई स्ट्रिंग मौजूद है, तो यह मैच करता है.

  • queryEquals

    string ज़रूरी नहीं

    अगर यूआरएल का क्वेरी सेगमेंट, किसी स्ट्रिंग से मैच करता है, तो यह शर्त पूरी हो जाती है.

  • queryPrefix

    string ज़रूरी नहीं

    अगर यूआरएल का क्वेरी सेगमेंट, किसी स्ट्रिंग से शुरू होता है, तो यह मैच करता है.

  • querySuffix

    string ज़रूरी नहीं

    अगर यूआरएल का क्वेरी सेगमेंट, किसी तय स्ट्रिंग पर खत्म होता है, तो यह मैच करता है.

  • स्कीम

    string[] ज़रूरी नहीं

    अगर यूआरएल की स्कीम, कलेक्शन में बताई गई किसी भी स्कीम से मैच करती है, तो यह मैच होता है.

  • urlContains

    string ज़रूरी नहीं

    अगर यूआरएल (फ़्रैगमेंट आइडेंटिफ़ायर के बिना) में कोई स्ट्रिंग मौजूद है, तो यह मैच करता है. अगर पोर्ट नंबर, डिफ़ॉल्ट पोर्ट नंबर से मैच करते हैं, तो उन्हें यूआरएल से हटा दिया जाता है.

  • urlEquals

    string ज़रूरी नहीं

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

  • urlMatches

    string ज़रूरी नहीं

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

  • urlPrefix

    string ज़रूरी नहीं

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

  • urlSuffix

    string ज़रूरी नहीं

    अगर यूआरएल (फ़्रैगमेंट आइडेंटिफ़ायर के बिना) किसी तय स्ट्रिंग पर खत्म होता है, तो यह मैच करता है. अगर पोर्ट नंबर, डिफ़ॉल्ट पोर्ट नंबर से मैच करते हैं, तो उन्हें यूआरएल से हटा दिया जाता है.