browser.offscreen

ब्यौरा

अनुमतियां

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

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

उपलब्धता

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

सर्विस वर्कर के पास DOM का ऐक्सेस नहीं होता. साथ ही, कई वेबसाइटों में कॉन्टेंट सिक्योरिटी से जुड़ी ऐसी नीतियां होती हैं जो कॉन्टेंट स्क्रिप्ट की सुविधाओं को सीमित करती हैं. ऑफ़स्क्रीन एपीआई की मदद से एक्सटेंशन, छिपे हुए दस्तावेज़ में DOM एपीआई का इस्तेमाल कर सकता है. इससे नई विंडो या टैब खोलने पर, उपयोगकर्ता अनुभव में रुकावट नहीं आती. 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);
    });
  }
}

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

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

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