ब्यौरा
ऑफ़स्क्रीन दस्तावेज़ बनाने और मैनेज करने के लिए, offscreen API का इस्तेमाल करें.
अनुमतियां
offscreenऑफ़स्क्रीन एपीआई का इस्तेमाल करने के लिए, एक्सटेंशन मेनिफ़ेस्ट में जाकर, "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 await matchedClients.some(client => {
client.url.includes(chrome.runtime.id);
});
}
}
टाइप
CreateParameters
प्रॉपर्टी
-
वजह
स्ट्रिंग
डेवलपर से मिली स्ट्रिंग, जो बैकग्राउंड में संदर्भ की ज़रूरत के बारे में ज़्यादा विस्तार से बताती है. उपयोगकर्ता एजेंट _मई_ इसका इस्तेमाल, उपयोगकर्ता को दिखाने के लिए कर सकता है.
-
वजहें
वजह[]
एक्सटेंशन की वजह से ऑफ़स्क्रीन दस्तावेज़ बनाया जा रहा है.
-
यूआरएल
स्ट्रिंग
दस्तावेज़ में लोड किया जाने वाला (रिलेटिव) यूआरएल.
Reason
Enum
"टेस्टिंग"
एक वजह, जिसका इस्तेमाल सिर्फ़ टेस्टिंग के लिए किया जाता है.
"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 API के साथ इंटरैक्ट करने की ज़रूरत है या नहीं.
"LOCAL_STORAGE"
यह बताता है कि ऑफ़स्क्रीन दस्तावेज़ को localStorage का ऐक्सेस चाहिए.
"WorkERS"
यह बताता है कि ऑफ़स्क्रीन दस्तावेज़, कर्मचारियों की संख्या बढ़ाने के लिए ज़रूरी है.
"BATTERY_STATUS"
बताता है कि ऑफ़स्क्रीन दस्तावेज़ के लिए navigator.getBattery का इस्तेमाल करना ज़रूरी है.
"MATCH_MEDIA"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ के लिए, window.matchMedia का इस्तेमाल करना ज़रूरी है.
"GEOLOCATION"
इससे पता चलता है कि ऑफ़स्क्रीन दस्तावेज़ के लिए, navigator.geolocation का इस्तेमाल करना ज़रूरी है.
तरीके
closeDocument()
chrome.offscreen.closeDocument(
callback?: function,
)
एक्सटेंशन के लिए वर्तमान में खुला ऑफ़स्क्रीन दस्तावेज़ बंद करता है.
पैरामीटर
-
कॉलबैक
फ़ंक्शन ज़रूरी नहीं
callbackपैरामीटर ऐसा दिखता है:()=>void
रिटर्न
-
Promise<void>
प्रॉमिस, मेनिफ़ेस्ट V3 और इसके बाद के वर्शन में काम करता है. हालांकि, पुराने सिस्टम के साथ काम करने के लिए कॉलबैक दिए जाते हैं. आप एक ही फ़ंक्शन कॉल पर दोनों का इस्तेमाल नहीं कर सकते. प्रॉमिस उसी टाइप के साथ रिज़ॉल्व हो जाती है जिसे कॉलबैक को पास किया जाता है.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
एक्सटेंशन के लिए एक नया ऑफ़स्क्रीन दस्तावेज़ बनाता है.
पैरामीटर
-
पैरामीटर
ऑफ़स्क्रीन दस्तावेज़ बनाने के लिए जानकारी देने वाले पैरामीटर.
-
कॉलबैक
फ़ंक्शन ज़रूरी नहीं
callbackपैरामीटर ऐसा दिखता है:()=>void
रिटर्न
-
Promise<void>
प्रॉमिस, मेनिफ़ेस्ट V3 और इसके बाद के वर्शन में काम करता है. हालांकि, पुराने सिस्टम के साथ काम करने के लिए कॉलबैक दिए जाते हैं. आप एक ही फ़ंक्शन कॉल पर दोनों का इस्तेमाल नहीं कर सकते. प्रॉमिस उसी टाइप के साथ रिज़ॉल्व हो जाती है जिसे कॉलबैक को पास किया जाता है.