chrome.offscreen

ब्यौरा

अनुमतियां

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

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

उपलब्धता

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

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

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

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

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

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

chrome.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 = chrome.runtime.getURL(path);
  const existingContexts = await chrome.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

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

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

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

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

  // Send message to offscreen document
  chrome.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 chrome.runtime) {
    const contexts = await chrome.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(chrome.runtime.id);
    });
  }
}

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

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