chrome.userScripts

ब्यौरा

उपयोगकर्ता स्क्रिप्ट के कॉन्टेक्स्ट में उपयोगकर्ता स्क्रिप्ट चलाने के लिए, userScripts API का इस्तेमाल करें.

अनुमतियां

userScripts

chrome.userScripts API का इस्तेमाल करने के लिए, अपनी Manifest.json और "host_permissions" में उन साइटों के लिए "userScripts" अनुमति जोड़ें जिन पर आपको स्क्रिप्ट चलानी हैं.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

उपलब्धता

Chrome 120 और इसके बाद के वर्शन MV3+

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

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

एक्सटेंशन उपयोगकर्ताओं के लिए डेवलपर मोड

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

1. नए टैब में chrome://extensions डालकर, एक्सटेंशन पेज पर जाएं. (डिज़ाइन के हिसाब से, chrome:// यूआरएल लिंक नहीं किए जा सकते.)

2. डेवलपर मोड के आगे मौजूद टॉगल स्विच पर क्लिक करके, डेवलपर मोड चालू करें.

   

   एक्सटेंशन पेज (chrome://extensions)

डेवलपर मोड चालू है या नहीं, यह देखने के लिए यह देखा जा सकता है कि chrome.userScripts से कोई गड़बड़ी दिखती है या नहीं. उदाहरण के लिए:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

अलग-अलग जगहों पर काम करें

उपयोगकर्ता और कॉन्टेंट, दोनों ही स्क्रिप्ट किसी सुनसान दुनिया में या मुख्य दुनिया में चल सकती हैं. आइसोलेटेड वर्ल्ड, एक्ज़ीक्यूशन का ऐसा एनवायरमेंट है जिसे किसी होस्ट पेज या अन्य एक्सटेंशन से ऐक्सेस नहीं किया जा सकता. इससे उपयोगकर्ता स्क्रिप्ट को, होस्ट पेज या अन्य एक्सटेंशन की उपयोगकर्ता और कॉन्टेंट स्क्रिप्ट पर असर डाले बिना, JavaScript एनवायरमेंट में बदलाव करने की सुविधा मिलती है. इसके ठीक उलट, उपयोगकर्ता स्क्रिप्ट (और कॉन्टेंट स्क्रिप्ट), होस्ट पेज या दूसरे एक्सटेंशन के उपयोगकर्ता और कॉन्टेंट स्क्रिप्ट को नहीं दिखती हैं. मुख्य दुनिया में चल रही स्क्रिप्ट, होस्ट पेजों और अन्य एक्सटेंशन के लिए ऐक्सेस की जा सकती हैं. साथ ही, ये होस्ट पेजों और अन्य एक्सटेंशन को दिखती हैं. दुनिया चुनने के लिए, userScripts.register() पर कॉल करते समय "USER_SCRIPT" या "MAIN" को पास करें.

USER_SCRIPT दुनिया के लिए कॉन्टेंट की सुरक्षा नीति कॉन्फ़िगर करने के लिए, userScripts.configureWorld() को कॉल करें:

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

मैसेज सेवा

कॉन्टेंट स्क्रिप्ट और ऑफ़स्क्रीन दस्तावेज़ों की तरह, उपयोगकर्ता स्क्रिप्ट मैसेज सेवा का इस्तेमाल करके, एक्सटेंशन के दूसरे हिस्सों के साथ बातचीत करती हैं. इसका मतलब है कि वे runtime.sendMessage() और runtime.connect() को कॉल कर सकते हैं, जैसा कि एक्सटेंशन के किसी भी दूसरे हिस्से में किया जाता है. हालांकि, ये सिर्फ़ खास इवेंट हैंडलर का इस्तेमाल करके मिलते हैं (इसका मतलब है कि वे onMessage या onConnect का इस्तेमाल नहीं करते). इन हैंडलर को runtime.onUserScriptMessage और runtime.onUserScriptConnect कहा जाता है. खास हैंडलर की मदद से, उपयोगकर्ता स्क्रिप्ट के मैसेज आसानी से पहचाने जा सकते हैं. इस तरह की स्क्रिप्ट पर भरोसा नहीं किया जा सकता.

मैसेज भेजने से पहले, आपको configureWorld() को कॉल करना होगा. इसमें messaging तर्क को true पर सेट किया गया होगा. ध्यान दें कि csp और messaging, दोनों आर्ग्युमेंट को एक साथ पास किया जा सकता है.

chrome.userScripts.configureWorld({
  messaging: true
});

एक्सटेंशन के अपडेट

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

उदाहरण

यह उदाहरण, सैंपल डेटा स्टोर करने की हमारी जगह में मौजूद userScript सैंपल से लिया गया है.

स्क्रिप्ट रजिस्टर करना

नीचे दिए गए उदाहरण में, register() को किया गया बेसिक कॉल दिखाया गया है. पहला तर्क, रजिस्टर की जाने वाली स्क्रिप्ट को तय करने वाले ऑब्जेक्ट का कलेक्शन होता है. यहां दिखाए गए विकल्पों से ज़्यादा विकल्प हैं.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

टाइप

ExecutionWorld

उपयोगकर्ता स्क्रिप्ट को चलाने के लिए JavaScript की दुनिया.

Enum

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

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

RegisteredUserScript

प्रॉपर्टी

• allFrames

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

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

• excludeGlobs

  स्ट्रिंग[] ज़रूरी नहीं है

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

• excludeMatches

  स्ट्रिंग[] ज़रूरी नहीं है

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

• id

  स्ट्रिंग

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

• includeGlobs

  स्ट्रिंग[] ज़रूरी नहीं है

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

• js

  ScriptSource[]

  ScriptSource ऑब्जेक्ट की सूची, जो मिलते-जुलते पेजों में इंजेक्ट की जाने वाली स्क्रिप्ट के सोर्स तय करती है.

• मैच करता है

  स्ट्रिंग[] ज़रूरी नहीं है

  इससे पता चलता है कि इस उपयोगकर्ता स्क्रिप्ट को किन पेजों में इंजेक्ट किया जाएगा. इन स्ट्रिंग के सिंटैक्स के बारे में ज़्यादा जानकारी के लिए, मिलते-जुलते पैटर्न देखें. ${ref:register} के लिए यह प्रॉपर्टी तय करना ज़रूरी है.

• runAt

  RunAt ज़रूरी नहीं

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

• दुनिया

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

  वह JavaScript एक्ज़ीक्यूशन एनवायरमेंट जिसमें स्क्रिप्ट चलाना है. डिफ़ॉल्ट वैल्यू `USER_SCRIPT` है.

ScriptSource

प्रॉपर्टी

• कोड

  स्ट्रिंग ज़रूरी नहीं

  इस स्ट्रिंग में इंजेक्ट करने के लिए JavaScript कोड होता है. file या code में से कोई एक बताना ज़रूरी है.

• फ़ाइल

  स्ट्रिंग ज़रूरी नहीं

  एक्सटेंशन की रूट डायरेक्ट्री के संबंध में इंजेक्ट करने के लिए JavaScript फ़ाइल का पाथ. file या code में से कोई एक बताना ज़रूरी है.

UserScriptFilter

प्रॉपर्टी

• ids

  स्ट्रिंग[] ज़रूरी नहीं है

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

WorldProperties

प्रॉपर्टी

• सीएसपी

  स्ट्रिंग ज़रूरी नहीं

  दुनिया का csp तय करता है. डिफ़ॉल्ट तौर पर, यह `ISOLATED` वर्ल्ड सीएसपी होता है.

• मैसेज सेवा

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

  इस नीति से पता चलता है कि मैसेजिंग एपीआई सार्वजनिक किए गए हैं या नहीं. डिफ़ॉल्ट वैल्यू false है.

तरीके

configureWorld()

वादा

chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

यह नीति, `USER_SCRIPT` एक्ज़ीक्यूशन एनवायरमेंट को कॉन्फ़िगर करती है.

पैरामीटर

• प्रॉपर्टी

  WorldProperties

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

• कॉलबैक

  फ़ंक्शन ज़रूरी नहीं

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

  ()=>void

रिटर्न

• Promise<void>

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

getScripts()

वादा

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

पैरामीटर

• फ़िल्‍टर

  UserScriptFilter ज़रूरी नहीं

  अगर बताया गया है, तो यह तरीका सिर्फ़ वही उपयोगकर्ता स्क्रिप्ट दिखाता है जो इससे मेल खाती हैं.

• कॉलबैक

  फ़ंक्शन ज़रूरी नहीं

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

  (scripts: RegisteredUserScript[])=>void

  • स्क्रिप्ट

    RegisteredUserScript[]

रिटर्न

• Promise<RegisteredUserScript[]>

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

register()

वादा

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

पैरामीटर

• स्क्रिप्ट

  RegisteredUserScript[]

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

• कॉलबैक

  फ़ंक्शन ज़रूरी नहीं

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

  ()=>void

रिटर्न

• Promise<void>

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

unregister()

वादा

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

पैरामीटर

• फ़िल्‍टर

  UserScriptFilter ज़रूरी नहीं

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

• कॉलबैक

  फ़ंक्शन ज़रूरी नहीं

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

  ()=>void

रिटर्न

• Promise<void>

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

update()

वादा

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

पैरामीटर

• स्क्रिप्ट

  RegisteredUserScript[]

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

• कॉलबैक

  फ़ंक्शन ज़रूरी नहीं

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

  ()=>void

रिटर्न

• Promise<void>

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