browser.declarativeContent

ब्यौरा

chrome.declarativeContent एपीआई का इस्तेमाल करके, पेज के कॉन्टेंट के हिसाब से कार्रवाइयां की जा सकती हैं. इसके लिए, पेज का कॉन्टेंट पढ़ने की अनुमति की ज़रूरत नहीं होती.

अनुमतियां

declarativeContent

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

अहम जानकारी: एक्सटेंशन की कार्रवाई, एक्सटेंशन के टूलबार आइकॉन को कंट्रोल करती है.

Declarative Content API की मदद से, किसी वेब पेज के यूआरएल के आधार पर एक्सटेंशन की कार्रवाई को चालू किया जा सकता है. इसके अलावा, अगर कोई सीएसएस सिलेक्टर, पेज पर मौजूद किसी एलिमेंट से मैच करता है, तो भी ऐसा किया जा सकता है. इसके लिए, होस्ट की अनुमतियां जोड़ने या कॉन्टेंट स्क्रिप्ट इंजेक्ट करने की ज़रूरत नहीं होती.

जब उपयोगकर्ता एक्सटेंशन की कार्रवाई पर क्लिक करे, तो पेज के साथ इंटरैक्ट करने के लिए activeTab अनुमति का इस्तेमाल करें.

नियम

नियमों में शर्तें और कार्रवाइयां शामिल होती हैं. अगर इनमें से कोई भी शर्त पूरी होती है, तो सभी कार्रवाइयां पूरी की जाती हैं. ये कार्रवाइयां setIcon() और showAction() हैं.

PageStateMatcher, वेब पेजों से सिर्फ़ तब मैच करता है, जब लिस्ट में शामिल सभी शर्तें पूरी होती हैं. यह किसी पेज के यूआरएल, सीएसएस कंपाउंड सिलेक्टर या किसी पेज की बुकमार्क की गई स्थिति से मैच कर सकता है. यहां दिया गया नियम, पासवर्ड फ़ील्ड मौजूद होने पर Google पेजों पर एक्सटेंशन की कार्रवाई को चालू करता है:

let rule1 = {
  conditions: [
    new browser.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new browser.declarativeContent.ShowAction() ]
};

सफलता: सभी शर्तें और कार्रवाइयां, कंस्ट्रक्टर का इस्तेमाल करके बनाई जाती हैं. जैसा कि पिछले उदाहरण में दिखाया गया है.

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

let rule2 = {
  conditions: [
    new browser.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new browser.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new browser.declarativeContent.ShowAction() ]
};

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

browser.runtime.onInstalled.addListener(function(details) {
  browser.declarativeContent.onPageChanged.removeRules(undefined, function() {
    browser.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

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

activeTab अनुमति की मदद से, आपका एक्सटेंशन अनुमति से जुड़ी कोई भी चेतावनी नहीं दिखाएगा. साथ ही, जब उपयोगकर्ता एक्सटेंशन की कार्रवाई पर क्लिक करेगा, तो यह सिर्फ़ काम के पेजों पर चलेगा.

पेज के यूआरएल का मिलान

यूआरएल की शर्तें पूरी होने पर, PageStateMatcher.pageurl मैच होता है. सबसे सामान्य शर्तें, होस्ट, पाथ या यूआरएल को जोड़ने से बनती हैं. इसके बाद, 'शामिल है', 'इसके बराबर है', 'प्रीफ़िक्स' या 'सफ़िक्स' आता है. यहां दी गई टेबल में कुछ उदाहरण दिए गए हैं:

नियम और शर्तें	मैच
{ hostSuffix: 'google.com' }	Google के सभी यूआरएल
{ pathPrefix: '/docs/extensions' }	एक्सटेंशन के दस्तावेज़ों के यूआरएल
{ urlContains: 'developer.chrome.com' }	Chrome डेवलपर के दस्तावेज़ों के सभी यूआरएल

सभी शर्तें केस-सेंसिटिव होती हैं. शर्तों की पूरी सूची देखने के लिए, UrlFilter देखें.

सीएसएस मैचिंग

PageStateMatcher.css की शर्तें कंपाउंड सिलेक्टर होनी चाहिए. इसका मतलब है कि सिलेक्टर में व्हाइटस्पेस या ">" जैसे कॉम्बिनेटर शामिल नहीं किए जा सकते. इससे Chrome को सिलेक्टर को ज़्यादा बेहतर तरीके से मैच करने में मदद मिलती है.

कंपाउंड सिलेक्टर (ठीक है)	जटिल सिलेक्टर (सही नहीं है)
a	div p
iframe.special[src^='http']	p>span.highlight
ns|*	p + ol
#abcd:checked	p::first-line

सीएसएस की शर्तें सिर्फ़ दिखाए गए एलिमेंट से मैच करती हैं: अगर आपके सिलेक्टर से मैच करने वाला कोई एलिमेंट display:none है या उसका कोई पैरंट एलिमेंट display:none है, तो शर्त मैच नहीं करती. visibility:hidden के साथ स्टाइल किए गए एलिमेंट, स्क्रीन से बाहर रखे गए एलिमेंट या अन्य एलिमेंट से छिपाए गए एलिमेंट, अब भी आपकी शर्त से मैच कर सकते हैं.

बुकमार्क किए गए राज्य से मैच करना

PageStateMatcher.isBookmarked शर्त की मदद से, उपयोगकर्ता की प्रोफ़ाइल में मौजूदा यूआरएल की बुकमार्क की गई स्थिति को मैच किया जा सकता है. इस शर्त का इस्तेमाल करने के लिए, एक्सटेंशन के मेनिफ़ेस्ट में "बुकमार्क" की अनुमति का एलान करना ज़रूरी है.

टाइप

ImageDataType

https://developer.mozilla.org/en-US/docs/Web/API/ImageData देखें.

टाइप

ImageData

PageStateMatcher

यह फ़ंक्शन, कई शर्तों के आधार पर किसी वेब पेज की स्थिति से मैच करता है.

प्रॉपर्टी

• कंस्ट्रक्टर

  void

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

  (arg: PageStateMatcher) => {...}

  • arg

    PageStateMatcher

  • returns

    PageStateMatcher

• css

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

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

• isBookmarked

  बूलियन ज़रूरी नहीं

  Chrome 45+ browser.* Chrome 148 से

  अगर पेज की बुकमार्क की गई स्थिति, बताई गई वैल्यू के बराबर है, तो यह मैच होती है. इसके लिए, बुकमार्क की अनुमति ज़रूरी है.

• pageUrl

  UrlFilter ज़रूरी नहीं है

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

RequestContentScript

कॉन्टेंट स्क्रिप्ट को इंजेक्ट करने वाला डिक्लेरेटिव इवेंट ऐक्शन.

चेतावनी: यह कार्रवाई अब भी एक्सपेरिमेंट के तौर पर उपलब्ध है. साथ ही, यह Chrome के स्टेबल बिल्ड पर काम नहीं करती.

प्रॉपर्टी

• कंस्ट्रक्टर

  void

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

  (arg: RequestContentScript) => {...}

  • arg

    RequestContentScript

  • returns

    RequestContentScript

• allFrames

  बूलियन ज़रूरी नहीं

  कॉन्टेंट स्क्रिप्ट, मैच होने वाले पेज के सभी फ़्रेम में चलती है या सिर्फ़ सबसे ऊपर वाले फ़्रेम में. डिफ़ॉल्ट रूप से, यह कार्रवाई false पर सेट रहती है.

• css

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

  कॉन्टेंट स्क्रिप्ट के हिस्से के तौर पर इंजेक्ट की जाने वाली सीएसएस फ़ाइलों के नाम.

• js

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

  कॉन्टेंट स्क्रिप्ट के हिस्से के तौर पर इंजेक्ट की जाने वाली JavaScript फ़ाइलों के नाम.

• matchAboutBlank

  बूलियन ज़रूरी नहीं

  about:blank और about:srcdoc पर कॉन्टेंट स्क्रिप्ट को शामिल करना है या नहीं. डिफ़ॉल्ट रूप से, यह कार्रवाई false पर सेट रहती है.

SetIcon

डिक्लेरेटिव इवेंट ऐक्शन, जो एक्सटेंशन के पेज ऐक्शन या ब्राउज़र ऐक्शन के लिए, n-dip स्क्वेयर आइकॉन सेट करता है. ऐसा तब होता है, जब उससे जुड़ी शर्तें पूरी होती हैं. इस कार्रवाई का इस्तेमाल, होस्ट की अनुमतियों के बिना किया जा सकता है. हालांकि, एक्सटेंशन में पेज या ब्राउज़र ऐक्शन होना चाहिए.

imageData या path में से कोई एक वैल्यू दी जानी चाहिए. दोनों ही डिक्शनरी हैं, जो कई पिक्सेल को इमेज के तौर पर मैप करती हैं. imageData में इमेज को ImageData ऑब्जेक्ट के तौर पर दिखाया जाता है. उदाहरण के लिए, canvas एलिमेंट से. वहीं, path में इमेज को एक्सटेंशन के मेनिफ़ेस्ट के हिसाब से, इमेज फ़ाइल के पाथ के तौर पर दिखाया जाता है. अगर scale स्क्रीन पिक्सल, डिवाइस-इंडिपेंडेंट पिक्सल में फ़िट हो जाते हैं, तो scale * n आइकॉन का इस्तेमाल किया जाता है. अगर वह स्केल मौजूद नहीं है, तो किसी दूसरी इमेज का साइज़ बदलकर, ज़रूरी साइज़ के मुताबिक कर दिया जाता है.

प्रॉपर्टी

• कंस्ट्रक्टर

  void

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

  (arg: SetIcon) => {...}

  • arg

    SetIcon

  • returns

    SetIcon

• imageData

  ImageData | object ज़रूरी नहीं

  सेट किए जाने वाले आइकॉन को दिखाने वाला ImageData ऑब्जेक्ट या डिक्शनरी {size -> ImageData}. अगर आइकॉन को डिक्शनरी के तौर पर तय किया गया है, तो इस्तेमाल की जाने वाली इमेज को स्क्रीन की पिक्सल डेंसिटी के आधार पर चुना जाता है. अगर एक स्क्रीन स्पेस यूनिट में फ़िट होने वाले इमेज पिक्सल की संख्या scale के बराबर है, तो scale * n साइज़ वाली इमेज चुनी जाती है. यहां n, यूज़र इंटरफ़ेस (यूआई) में आइकॉन का साइज़ है. कम से कम एक इमेज की जानकारी देना ज़रूरी है. ध्यान दें कि details.imageData = foo, details.imageData = {'16': foo} के बराबर है.

ShowAction

Chrome 97+ browser.* Chrome 148 से

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

जिन पेजों पर शर्तें पूरी नहीं होती हैं वहां एक्सटेंशन के टूलबार की कार्रवाई ग्रे-स्केल होगी. साथ ही, उस पर क्लिक करने से कार्रवाई ट्रिगर होने के बजाय, कॉन्टेक्स्ट मेन्यू खुल जाएगा.

प्रॉपर्टी

• कंस्ट्रक्टर

  void

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

  (arg: ShowAction) => {...}

  • arg

    ShowAction

  • returns

    ShowAction

ShowPageAction

Chrome 97 के बाद से इस्तेमाल नहीं किया जा रहा है

कृपया declarativeContent.ShowAction का इस्तेमाल करें.

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

जिन पेजों पर शर्तें पूरी नहीं होती हैं वहां एक्सटेंशन के टूलबार की कार्रवाई ग्रे-स्केल होगी. साथ ही, उस पर क्लिक करने से कार्रवाई ट्रिगर होने के बजाय, कॉन्टेक्स्ट मेन्यू खुल जाएगा.

प्रॉपर्टी

• कंस्ट्रक्टर

  void

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

  (arg: ShowPageAction) => {...}

  • arg

    ShowPageAction

  • returns

    ShowPageAction

इवेंट

onPageChanged

Declarative Event API उपलब्ध कराता है. इसमें addRules, removeRules, और getRules शामिल हैं.

शर्तें

PageStateMatcher

कार्रवाइयां

RequestContentScript

SetIcon

ShowPageAction

ShowAction