browser.offscreen

ब्यौरा

ऑफ़स्क्रीन दस्तावेज़ बनाने और उन्हें मैनेज करने के लिए, offscreen एपीआई का इस्तेमाल करें.

अनुमतियां

offscreen

Offscreen API का इस्तेमाल करने के लिए, एक्सटेंशन मेनिफ़ेस्ट में "offscreen" अनुमति का एलान करें. उदाहरण के लिए:

{
  "name": "My extension",
  ...
  "permissions": [
    "offscreen"
  ],
  ...
}

उपलब्धता

Chrome 109+ browser.* Chrome 148 से MV3+

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

सर्विस वर्कर के पास डीओएम का ऐक्सेस नहीं होता. साथ ही, कई वेबसाइटों में कॉन्टेंट की सुरक्षा के लिए ऐसी नीतियां होती हैं जो कॉन्टेंट स्क्रिप्ट की सुविधाओं को सीमित करती हैं. Offscreen API, एक्सटेंशन को छिपे हुए दस्तावेज़ में DOM API का इस्तेमाल करने की अनुमति देता है. इसके लिए, उपयोगकर्ता को नई विंडो या टैब खोलने की ज़रूरत नहीं पड़ती. runtime एपीआई, एक्सटेंशन का इकलौता ऐसा एपीआई है जो ऑफ़स्क्रीन दस्तावेज़ों के साथ काम करता है.

ऑफ़स्क्रीन दस्तावेज़ों के तौर पर लोड किए गए पेजों को, अन्य तरह के एक्सटेंशन पेजों से अलग तरीके से मैनेज किया जाता है. एक्सटेंशन की अनुमतियां, ऑफ़स्क्रीन दस्तावेज़ों पर लागू होती हैं. हालांकि, एक्सटेंशन एपीआई के ऐक्सेस पर सीमाएं लागू होती हैं. उदाहरण के लिए, browser.runtime एपीआई ही ऐसा एक्सटेंशन एपीआई है जो ऑफ़स्क्रीन दस्तावेज़ों के साथ काम करता है. इसलिए, मैसेज सेवा को मैनेज करने के लिए, उस एपीआई के सदस्यों का इस्तेमाल करना ज़रूरी है.

ऑफ़स्क्रीन दस्तावेज़, सामान्य पेजों से अलग तरीके से काम करते हैं. इसके बारे में यहां बताया गया है:

• ऑफ़स्क्रीन दस्तावेज़ का यूआरएल, एक्सटेंशन के साथ बंडल की गई स्टैटिक एचटीएमएल फ़ाइल होनी चाहिए.
• ऑफ़स्क्रीन दस्तावेज़ों पर फ़ोकस नहीं किया जा सकता.
• ऑफ़स्क्रीन दस्तावेज़, window का एक इंस्टेंस होता है. हालांकि, इसकी opener प्रॉपर्टी की वैल्यू हमेशा null होती है.
• किसी एक्सटेंशन पैकेज में कई ऑफ़स्क्रीन दस्तावेज़ हो सकते हैं. हालांकि, इंस्टॉल किए गए एक्सटेंशन में एक समय पर सिर्फ़ एक दस्तावेज़ खोला जा सकता है. अगर एक्सटेंशन, स्प्लिट मोड में चल रहा है और गुप्त मोड वाली प्रोफ़ाइल चालू है, तो सामान्य और गुप्त मोड वाली प्रोफ़ाइल, दोनों में एक-एक ऑफ़स्क्रीन दस्तावेज़ हो सकता है.

ऑफ़स्क्रीन दस्तावेज़ बनाने और बंद करने के लिए, browser.offscreen.createDocument() और browser.offscreen.closeDocument() का इस्तेमाल करें. createDocument() के लिए, दस्तावेज़ का url, वजह, और सही वजह बताना ज़रूरी है:

browser.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

वजहें

मान्य वजहों की सूची देखने के लिए, वजहें सेक्शन देखें. दस्तावेज़ बनाते समय, उसकी समयसीमा तय करने के लिए वजहें सेट की जाती हैं. AUDIO_PLAYBACK वजह से, दस्तावेज़ को 30 सेकंड के बाद बंद होने के लिए सेट किया जाता है. इस दौरान, कोई ऑडियो नहीं चलता. अन्य वजहों से, लाइफ़टाइम लिमिट सेट नहीं होती.

उदाहरण

ऑफ़स्क्रीन दस्तावेज़ की लाइफ़साइकल को मैनेज करना

यहां दिए गए उदाहरण में, यह पक्का करने का तरीका बताया गया है कि ऑफ़स्क्रीन दस्तावेज़ मौजूद है. setupOffscreenDocument() फ़ंक्शन, runtime.getContexts() को कॉल करता है, ताकि किसी मौजूदा ऑफ़स्क्रीन दस्तावेज़ को ढूंढा जा सके. अगर दस्तावेज़ पहले से मौजूद नहीं है, तो उसे बनाया जा सके.

let creating; // A global promise to avoid concurrency issues
async function setupOffscreenDocument(path) {
  // Check all windows controlled by the service worker to see if one
  // of them is the offscreen document with the given path
  const offscreenUrl = browser.runtime.getURL(path);
  const existingContexts = await browser.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

  if (existingContexts.length > 0) {
    return;
  }

  // create offscreen document
  if (creating) {
    await creating;
  } else {
    creating = browser.offscreen.createDocument({
      url: path,
      reasons: ['CLIPBOARD'],
      justification: 'reason for needing the document',
    });
    await creating;
    creating = null;
  }
}

किसी ऑफ़स्क्रीन दस्तावेज़ को मैसेज भेजने से पहले, setupOffscreenDocument() को कॉल करके पक्का करें कि दस्तावेज़ मौजूद है. इसके बारे में यहां दिए गए उदाहरण में बताया गया है.

browser.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  browser.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

पूरे उदाहरण देखने के लिए, GitHub पर offscreen-clipboard और offscreen-dom डेमो देखें.

Chrome 116 से पहले के वर्शन में: देखें कि कोई ऑफ़स्क्रीन दस्तावेज़ खुला है या नहीं

runtime.getContexts() को Chrome 116 में जोड़ा गया था. Chrome के पुराने वर्शन में, किसी मौजूदा ऑफ़स्क्रीन दस्तावेज़ की जांच करने के लिए, clients.matchAll() का इस्तेमाल करें:

async function hasOffscreenDocument() {
  if ('getContexts' in browser.runtime) {
    const contexts = await browser.runtime.getContexts({
      contextTypes: ['OFFSCREEN_DOCUMENT'],
      documentUrls: [OFFSCREEN_DOCUMENT_PATH]
    });
    return Boolean(contexts.length);
  } else {
    const matchedClients = await clients.matchAll();
    return matchedClients.some(client => {
      return client.url.includes(browser.runtime.id);
    });
  }
}

टाइप

CreateParameters

प्रॉपर्टी

• वजह

  स्ट्रिंग

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

• वजहें

  वजह[]

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

• url

  स्ट्रिंग

  दस्तावेज़ में लोड करने के लिए (रिलेटिव) यूआरएल.

Reason

Enum

"TESTING"
इस वजह का इस्तेमाल सिर्फ़ टेस्टिंग के लिए किया जाता है.

"AUDIO_PLAYBACK"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़, ऑडियो चलाने के लिए ज़िम्मेदार है.

"IFRAME_SCRIPTING"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को iframe के कॉन्टेंट में बदलाव करने के लिए, iframe को एम्बेड और स्क्रिप्ट करना होगा.

"DOM_SCRAPING"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को iframe एम्बेड करना होगा और जानकारी निकालने के लिए, उसके डीओएम को स्क्रैप करना होगा.

"BLOBS"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को Blob ऑब्जेक्ट के साथ इंटरैक्ट करना होगा. इसमें URL.createObjectURL() भी शामिल है.

"DOM_PARSER"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को DOMParser API का इस्तेमाल करना होगा.

"USER_MEDIA"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को उपयोगकर्ता के मीडिया (जैसे, getUserMedia()) से मीडिया स्ट्रीम के साथ इंटरैक्ट करना होगा.

"DISPLAY_MEDIA"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को डिसप्ले मीडिया (जैसे, getDisplayMedia()) से मीडिया स्ट्रीम के साथ इंटरैक्ट करना होगा.

"WEB_RTC"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को WebRTC एपीआई इस्तेमाल करने की ज़रूरत है.

"CLIPBOARD"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को Clipboard API के साथ इंटरैक्ट करना होगा.

"LOCAL_STORAGE"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को localStorage का ऐक्सेस चाहिए.

"WORKERS"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को वर्कर जनरेट करने की ज़रूरत है.

"BATTERY_STATUS"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को navigator.getBattery का इस्तेमाल करना होगा.

"MATCH_MEDIA"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को window.matchMedia का इस्तेमाल करना होगा.

"GEOLOCATION"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ को navigator.geolocation का इस्तेमाल करना होगा.

तरीके

closeDocument()

browser.offscreen.closeDocument(): Promise<void>

एक्सटेंशन के लिए, फ़िलहाल खुले हुए ऑफ़स्क्रीन दस्तावेज़ को बंद करता है.

रिटर्न

• वादा<शून्य>

  ऑफ़स्क्रीन दस्तावेज़ बंद होने पर रिज़ॉल्व होने वाला प्रॉमिस.

createDocument()

browser.offscreen.createDocument(
  parameters: CreateParameters,
): Promise<void>

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

पैरामीटर

• पैरामीटर

  CreateParameters

  ऑफ़स्क्रीन दस्तावेज़ बनाने के लिए पैरामीटर.

रिटर्न

• वादा<शून्य>

  यह प्रॉमिस तब रिज़ॉल्व होता है, जब ऑफ़स्क्रीन दस्तावेज़ बन जाता है और उसका शुरुआती पेज लोड हो जाता है.

hasDocument()

Chrome 150+

browser.offscreen.hasDocument(): Promise<boolean>

इससे यह तय होता है कि एक्सटेंशन में कोई दस्तावेज़ चालू है या नहीं.

रिटर्न

• Promise<boolean>

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