chrome.userScripts

ब्यौरा

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

अनुमतियां

userScripts

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

{
  "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 कहा जाता है. खास हैंडलर की मदद से, उपयोगकर्ता स्क्रिप्ट से मिले मैसेज की पहचान करना आसान हो जाता है. ये मैसेज कम भरोसेमंद होते हैं.

मैसेज भेजने से पहले, आपको messaging आर्ग्युमेंट को true पर सेट करके, configureWorld() को कॉल करना होगा. ध्यान दें कि 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_SCRIPT"
यह उपयोगकर्ता स्क्रिप्ट के लिए खास तौर पर, स्क्रिप्ट को चलाने के माहौल के बारे में बताता है. साथ ही, इसे पेज के सीएसपी से छूट मिलती है.

RegisteredUserScript

प्रॉपर्टी

  • allFrames

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

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

  • excludeGlobs

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

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

  • excludeMatches

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

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

  • आईडी

    स्ट्रिंग

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

  • includeGlobs

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

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

  • js

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

    ScriptSource ऑब्जेक्ट की सूची, जो मैच करने वाले पेजों में इंजेक्ट की जाने वाली स्क्रिप्ट के सोर्स की जानकारी देती है. ${ref:register} के लिए, इस प्रॉपर्टी की वैल्यू देना ज़रूरी है. साथ ही, यह भी ज़रूरी है कि वैल्यू के तौर पर कोई खाली कलेक्शन न दिया गया हो.

  • मैच

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

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

  • runAt

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

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

  • दुनिया

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

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

  • worldId

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

    मंज़ूरी बाकी है

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

ScriptSource

प्रॉपर्टी

  • कोड

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

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

  • फ़ाइल

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

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

UserScriptFilter

प्रॉपर्टी

  • आईडी

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

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

WorldProperties

प्रॉपर्टी

  • csp

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

    दुनिया के सीएसपी के बारे में बताता है. डिफ़ॉल्ट रूप से, `ISOLATED` world csp सेट होता है.

  • मैसेज सेवा

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

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

  • worldId

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

    मंज़ूरी बाकी है

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

तरीके

configureWorld()

वादा करना 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

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

पैरामीटर

  • प्रॉपर्टी

    WorldProperties

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

  • कॉलबैक

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

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

    () => void

रिटर्न

  • Promise<void>

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

getScripts()

वादा करना 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

पैरामीटर

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

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

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

  • कॉलबैक

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

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

    (scripts: RegisteredUserScript[]) => void

रिटर्न

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

getWorldConfigurations()

वादा करना मंज़ूरी बाकी है
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

दुनिया भर के रजिस्टर किए गए सभी कॉन्फ़िगरेशन को वापस लाता है.

पैरामीटर

  • कॉलबैक

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

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

    (worlds: WorldProperties[]) => void

रिटर्न

  • Promise<WorldProperties[]>

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

register()

वादा करना 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

पैरामीटर

  • स्क्रिप्ट

    RegisteredUserScript[]

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

  • कॉलबैक

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

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

    () => void

रिटर्न

  • Promise<void>

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

resetWorldConfiguration()

वादा करना मंज़ूरी बाकी है
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

पैरामीटर

  • worldId

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

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

  • कॉलबैक

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

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

    () => void

रिटर्न

  • Promise<void>

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

unregister()

वादा करना 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

पैरामीटर

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

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

    अगर कोई पैटर्न तय किया गया है, तो यह तरीका सिर्फ़ उससे मैच होने वाली उपयोगकर्ता स्क्रिप्ट को अनरजिस्टर करता है.

  • कॉलबैक

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

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

    () => void

रिटर्न

  • Promise<void>

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

update()

वादा करना 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

पैरामीटर

  • स्क्रिप्ट

    RegisteredUserScript[]

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

  • कॉलबैक

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

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

    () => void

रिटर्न

  • Promise<void>

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