chrome.events

ब्यौरा

सिद्धांत और उनका इस्तेमाल

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

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

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

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

एलान वाले इवेंट हैंडलर

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

डिक्लेरेटिव इवेंट हैंडलर का इस्तेमाल घोषणात्मक 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 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

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

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

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

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

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

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

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

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

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

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

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

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

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

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