chrome.offscreen

ब्यौरा

अनुमतियां

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

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

उपलब्धता

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

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

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

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

• ऑफ़स्क्रीन दस्तावेज़ का यूआरएल, एक्सटेंशन के साथ बंडल की गई एक स्टैटिक एचटीएमएल फ़ाइल होनी चाहिए.
• ऑफ़स्क्रीन दस्तावेज़ों पर फ़ोकस नहीं किया जा सकता.
• ऑफ़स्क्रीन दस्तावेज़ 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 पर ऑफ़स्क्रीन-डॉम डेमो.

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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

chrome.offscreen.closeDocument(
  callback?: function,
)

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)