chrome.scripting

ब्यौरा

अलग-अलग कॉन्टेक्स्ट में स्क्रिप्ट को चलाने के लिए, chrome.scripting एपीआई का इस्तेमाल करें.

अनुमतियां

scripting

उपलब्धता

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

मेनिफ़ेस्ट

chrome.scripting एपीआई का इस्तेमाल करने के लिए, मेनिफ़ेस्ट में "scripting" अनुमति का एलान करें. साथ ही, उन पेजों के लिए होस्ट करने की अनुमतियां दें जिनमें स्क्रिप्ट इंजेक्ट करनी हैं. "host_permissions" कुंजी या "activeTab" अनुमति का इस्तेमाल करें. इससे होस्ट को कुछ समय के लिए अनुमतियां मिलती हैं. इस उदाहरण में, activeTab अनुमति का इस्तेमाल किया गया है.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

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

वेबसाइटों में JavaScript और सीएसएस इंजेक्ट करने के लिए, chrome.scripting एपीआई का इस्तेमाल किया जा सकता है. यह कॉन्टेंट स्क्रिप्ट की तरह ही काम करता है. हालांकि, chrome.scripting नेमस्पेस का इस्तेमाल करके, एक्सटेंशन रनटाइम के दौरान फ़ैसले ले सकते हैं.

इंजेक्शन के टारगेट

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

सिर्फ़ tabId फ़ील्ड को भरना ज़रूरी है. डिफ़ॉल्ट रूप से, इंजेक्शन, चुने गए टैब के मुख्य फ़्रेम में चलेगा.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

अगर आपको विज्ञापन को चुने गए टैब के सभी फ़्रेम में दिखाना है, तो allFrames बूलियन को true पर सेट करें.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

अलग-अलग फ़्रेम आईडी तय करके, किसी टैब के चुनिंदा फ़्रेम में भी स्क्रिप्ट डाली जा सकती है. फ़्रेम आईडी के बारे में ज़्यादा जानकारी के लिए, chrome.webNavigation एपीआई देखें.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

इंजेक्ट किया गया कोड

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

फ़ाइलें

फ़ाइलों को स्ट्रिंग के तौर पर तय किया जाता है. ये स्ट्रिंग, एक्सटेंशन की रूट डायरेक्ट्री के हिसाब से पाथ होती हैं. यह कोड, फ़ाइल script.js को टैब के मुख्य फ़्रेम में इंजेक्ट करेगा.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

रनटाइम फ़ंक्शन

scripting.executeScript() की मदद से JavaScript इंजेक्ट करते समय, फ़ाइल के बजाय एक्ज़ीक्यूट की जाने वाली फ़ंक्शन के बारे में जानकारी दी जा सकती है. यह फ़ंक्शन, मौजूदा एक्सटेंशन कॉन्टेक्स्ट के लिए उपलब्ध फ़ंक्शन वैरिएबल होना चाहिए.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

args प्रॉपर्टी का इस्तेमाल करके, इस समस्या को हल किया जा सकता है:

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

रनटाइम स्ट्रिंग

अगर किसी पेज में सीएसएस इंजेक्ट की जा रही है, तो css प्रॉपर्टी में इस्तेमाल की जाने वाली स्ट्रिंग भी तय की जा सकती है. यह विकल्प सिर्फ़ scripting.insertCSS() के लिए उपलब्ध है. scripting.executeScript() का इस्तेमाल करके स्ट्रिंग को लागू नहीं किया जा सकता.

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

नतीजों को मैनेज करना

JavaScript को चलाने के बाद मिले नतीजे, एक्सटेंशन को भेजे जाते हैं. हर फ़्रेम में एक नतीजा शामिल किया जाता है. मुख्य फ़्रेम, नतीजे के तौर पर मिले ऐरे में पहले इंडेक्स पर होता है. अन्य सभी फ़्रेम, किसी भी क्रम में हो सकते हैं.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() से कोई नतीजा नहीं मिलता.

प्रॉमिस

अगर स्क्रिप्ट को चलाने पर मिलने वाली वैल्यू एक प्रॉमिस है, तो Chrome, प्रॉमिस के पूरा होने का इंतज़ार करेगा और फिर वैल्यू दिखाएगा.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

उदाहरण

सभी डाइनैमिक कॉन्टेंट स्क्रिप्ट के लिए रजिस्ट्रेशन रद्द करें

इस स्निपेट में एक ऐसा फ़ंक्शन शामिल है जो डाइनैमिक कॉन्टेंट की उन सभी स्क्रिप्ट को अनरजिस्टर करता है जिन्हें एक्सटेंशन ने पहले रजिस्टर किया था.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

chrome.scripting एपीआई आज़माने के लिए, Chrome एक्सटेंशन के सैंपल रिपॉज़िटरी से स्क्रिप्टिंग सैंपल इंस्टॉल करें.

टाइप

ContentScriptFilter

Chrome 96 और इसके बाद के वर्शन

प्रॉपर्टी

  • ids

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

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

CSSInjection

प्रॉपर्टी

  • css

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

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

  • फ़ाइलें

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

    एक्सटेंशन की रूट डायरेक्ट्री के हिसाब से, इंजेक्ट की जाने वाली सीएसएस फ़ाइलों का पाथ. files और css में से किसी एक को तय करना ज़रूरी है.

  • origin

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

    इंजेक्शन के लिए स्टाइल का ऑरिजिन. डिफ़ॉल्ट रूप से, यह 'AUTHOR' पर सेट होती है.

  • टारगेट

    InjectionTarget

    सीएसएस को किस टारगेट में डालना है, इसकी जानकारी.

ExecutionWorld

Chrome 95+

यह JavaScript का वह एनवायरमेंट होता है जिसमें स्क्रिप्ट को एक्ज़ीक्यूट किया जाता है.

Enum

"ISOLATED"
यह आइसोलेटेड वर्ल्ड के बारे में बताता है. यह इस एक्सटेंशन के लिए यूनीक एक्ज़ीक्यूशन एनवायरमेंट होता है.

"MAIN"
यह DOM के मुख्य वर्ल्ड के बारे में बताता है. यह होस्ट पेज के JavaScript के साथ शेयर किया गया एक्ज़ीक्यूशन एनवायरमेंट होता है.

InjectionResult

प्रॉपर्टी

  • documentId

    स्ट्रिंग

    Chrome 106 और इसके बाद के वर्शन

    इंजेक्शन से जुड़ा दस्तावेज़.

  • frameId

    संख्या

    Chrome 90+

    इंजेक्शन से जुड़ा फ़्रेम.

  • नतीजा

    कोई भी ज़रूरी नहीं है

    स्क्रिप्ट को चलाने का नतीजा.

InjectionTarget

प्रॉपर्टी

  • allFrames

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

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

  • documentIds

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

    Chrome 106 और इसके बाद के वर्शन

    उन documentIds के आईडी जिनमें डेटा डालना है. अगर frameIds सेट है, तो इसे सेट नहीं किया जाना चाहिए.

  • frameIds

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

    उन फ़्रेम के आईडी जिनमें स्क्रिप्ट को इंजेक्ट करना है.

  • tabId

    संख्या

    उस टैब का आईडी जिसमें स्क्रिप्ट को इंजेक्ट करना है.

RegisteredContentScript

Chrome 96 और इसके बाद के वर्शन

प्रॉपर्टी

  • allFrames

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

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

  • css

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

    मैच करने वाले पेजों में इंजेक्ट की जाने वाली सीएसएस फ़ाइलों की सूची. इन्हें इस ऐरे में दिखने के क्रम में डाला जाता है. ऐसा पेज के लिए कोई भी डीओएम बनाने या दिखाने से पहले किया जाता है.

  • excludeMatches

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

    यह उन पेजों को बाहर रखता है जिनमें इस कॉन्टेंट स्क्रिप्ट को इंजेक्ट किया जाता है. इन स्ट्रिंग के सिंटैक्स के बारे में ज़्यादा जानने के लिए, मैच पैटर्न देखें.

  • आईडी

    स्ट्रिंग

    एपीआई कॉल में बताया गया कॉन्टेंट स्क्रिप्ट का आईडी. इसकी शुरुआत '_' से नहीं होनी चाहिए, क्योंकि इसे जनरेट की गई स्क्रिप्ट आईडी के लिए प्रीफ़िक्स के तौर पर रिज़र्व किया गया है.

  • js

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

    यह उन JavaScript फ़ाइलों की सूची होती है जिन्हें मिलते-जुलते पेजों में इंजेक्ट किया जाना है. इन्हें इस ऐरे में मौजूद क्रम के हिसाब से इंजेक्ट किया जाता है.

  • matchOriginAsFallback

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

    Chrome 119+

    इससे पता चलता है कि स्क्रिप्ट को उन फ़्रेम में इंजेक्ट किया जा सकता है या नहीं जहां यूआरएल में काम न करने वाली स्कीम शामिल है. जैसे: about:, data:, blob:, या filesystem:. ऐसे मामलों में, यूआरएल के ऑरिजिन की जांच की जाती है. इससे यह तय किया जाता है कि स्क्रिप्ट को इंजेक्ट किया जाना चाहिए या नहीं. अगर ऑरिजिन null है (जैसा कि data: यूआरएल के मामले में होता है), तो इस्तेमाल किया गया ऑरिजिन, मौजूदा फ़्रेम को बनाने वाला फ़्रेम या इस फ़्रेम पर नेविगेशन शुरू करने वाला फ़्रेम होता है. ध्यान दें कि यह पैरंट फ़्रेम नहीं हो सकता.

  • मैच

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

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

  • persistAcrossSessions

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

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

  • runAt

    RunAt optional

    इससे यह तय होता है कि JavaScript फ़ाइलों को वेब पेज में कब इंजेक्ट किया जाता है. डिफ़ॉल्ट वैल्यू और सुझाई गई वैल्यू document_idle है.

  • दुनिया

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

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

    JavaScript "world", जिसमें स्क्रिप्ट को चलाया जाता है. डिफ़ॉल्ट रूप से, यह ISOLATED पर सेट होती है.

ScriptInjection

प्रॉपर्टी

  • args

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

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

    दिए गए फ़ंक्शन में पास किए जाने वाले आर्ग्युमेंट. यह सिर्फ़ तब मान्य होता है, जब func पैरामीटर तय किया गया हो. ये आर्ग्युमेंट, JSON फ़ॉर्मैट में सेव किए जा सकने चाहिए.

  • फ़ाइलें

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

    इंजेक्ट की जाने वाली JS या CSS फ़ाइलों का पाथ. यह एक्सटेंशन की रूट डायरेक्ट्री के हिसाब से होता है. files या func में से किसी एक की जानकारी देना ज़रूरी है.

  • injectImmediately

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

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

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

  • टारगेट

    InjectionTarget

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

  • दुनिया

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

    Chrome 95+

    JavaScript "world", जिसमें स्क्रिप्ट को चलाया जाता है. डिफ़ॉल्ट रूप से, यह ISOLATED पर सेट होती है.

  • func

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

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

    इंजेक्ट करने के लिए JavaScript फ़ंक्शन. इस फ़ंक्शन को क्रम से लगाया जाएगा. इसके बाद, इसे इंजेक्शन के लिए क्रम से हटाया जाएगा. इसका मतलब है कि बाउंड पैरामीटर और एक्ज़ीक्यूशन कॉन्टेक्स्ट मिट जाएंगे. files या func में से किसी एक की जानकारी देना ज़रूरी है.

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

    () => {...}

StyleOrigin

स्टाइल में बदलाव का ऑरिजिन. ज़्यादा जानकारी के लिए, स्टाइल के ओरिजनल वर्शन देखें.

Enum

"AUTHOR"

"USER"

तरीके

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

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

पैरामीटर

  • इंजेक्शन

    ScriptInjection

    उस स्क्रिप्ट की जानकारी जिसे इंजेक्ट करना है.

रिटर्न

getRegisteredContentScripts()

Chrome 96 और इसके बाद के वर्शन 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

पैरामीटर

  • फ़िल्टर करें

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

    एक्सटेंशन की डाइनैमिक तौर पर रजिस्टर की गई स्क्रिप्ट को फ़िल्टर करने के लिए ऑब्जेक्ट.

रिटर्न

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

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

पैरामीटर

  • इंजेक्शन

    CSSInjection

    सम्मिलित की जाने वाली स्टाइल की जानकारी.

रिटर्न

  • Promise<void>

    Chrome 90+

registerContentScripts()

Chrome 96 और इसके बाद के वर्शन 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

यह एक्सटेंशन के लिए एक या उससे ज़्यादा कॉन्टेंट स्क्रिप्ट रजिस्टर करता है.

पैरामीटर

  • स्क्रिप्ट

    RegisteredContentScript[]

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

रिटर्न

  • Promise<void>

removeCSS()

Chrome 90+ 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

यह फ़ंक्शन, टारगेट कॉन्टेक्स्ट से उस सीएसएस स्टाइलशीट को हटाता है जिसे इस एक्सटेंशन ने पहले डाला था.

पैरामीटर

  • इंजेक्शन

    CSSInjection

    हटाए जाने वाले स्टाइल की जानकारी. ध्यान दें कि css, files, और origin प्रॉपर्टी की वैल्यू, insertCSS के ज़रिए डाली गई स्टाइलशीट से पूरी तरह मेल खानी चाहिए. मौजूद नहीं है ऐसी स्टाइलशीट को हटाने की कोशिश करने पर, कुछ नहीं होता.

रिटर्न

  • Promise<void>

unregisterContentScripts()

Chrome 96 और इसके बाद के वर्शन 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

यह एक्सटेंशन के लिए कॉन्टेंट स्क्रिप्ट को अनरजिस्टर करता है.

पैरामीटर

  • फ़िल्टर करें

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

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

रिटर्न

  • Promise<void>

updateContentScripts()

Chrome 96 और इसके बाद के वर्शन 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

यह एक्सटेंशन के लिए, एक या उससे ज़्यादा कॉन्टेंट स्क्रिप्ट को अपडेट करता है.

पैरामीटर

  • स्क्रिप्ट

    RegisteredContentScript[]

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

रिटर्न

  • Promise<void>