browser.offscreen

বিবরণ

অনুমতি

Offscreen API ব্যবহার করতে, এক্সটেনশন ম্যানিফেস্টে "offscreen" অনুমতি ঘোষণা করুন। যেমন:

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

উপলভ্যতা

ধারণা ও ব্যবহার

পরিষেবা কর্মীর DOM অ্যাক্সেস নেই এবং অনেক ওয়েবসাইটে কন্টেন্ট নিরাপত্তা নীতি আছে যা কন্টেন্ট স্ক্রিপ্টের কার্যকারিতা সীমিত করে। অফস্ক্রিন API, এক্সটেনশনকে নতুন উইন্ডো বা ট্যাব খুলে ব্যবহারকারীর অভিজ্ঞতা ব্যাহত না করেই লুকানো ডকুমেন্টে DOM API ব্যবহার করার অনুমতি দেয়। runtime API হল একমাত্র এক্সটেনশন API যা অফস্ক্রিন ডকুমেন্ট ব্যবহার করে।

অফস্ক্রিন ডকুমেন্ট হিসেবে লোড করা পৃষ্ঠাগুলি অন্যান্য ধরনের এক্সটেনশন পৃষ্ঠা থেকে আলাদাভাবে ম্যানেজ করা হয়। এক্সটেনশনের অনুমতি অফস্ক্রিন ডকুমেন্টেও প্রযোজ্য হয়, তবে এক্সটেনশন API অ্যাক্সেস করার ক্ষেত্রে সীমাবদ্ধতা থাকে। যেমন, browser.runtime API হল একমাত্র এক্সটেনশন API যা অফস্ক্রিন ডকুমেন্ট দ্বারা পরিচালিত হয়, তাই মেসেজিংকে সেই API-এর মেম্বার ব্যবহার করে ম্যানেজ করতে হবে।

অফস্ক্রিন ডকুমেন্ট কীভাবে সাধারণ পৃষ্ঠা থেকে আলাদা আচরণ করে তা নিচে উল্লেখ করা হল:

• অফস্ক্রিন ডকুমেন্টের URL অবশ্যই এক্সটেনশনের সাথে বান্ডেল করা একটি স্ট্যাটিক HTML ফাইল হতে হবে।
• স্ক্রিনের বাইরে থাকা ডকুমেন্টে ফোকাস করা যায় না।
• অফস্ক্রিন ডকুমেন্ট হল 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 কারণটি ৩০ সেকেন্ড পরে অডিও না বাজিয়েই ডকুমেন্ট বন্ধ করে দেয়। অন্যান্য সব কারণে লাইফটাইম সীমা সেট করা হয় না।

উদাহরণ

অফ-স্ক্রিন ডকুমেন্টের লাইফসাইকেল বজায় রাখা

নিচের উদাহরণ থেকে বোঝা যায় যে কীভাবে অফস্ক্রিন ডকুমেন্ট আছে কিনা তা নিশ্চিত করতে হয়। আগে থেকে থাকা অফস্ক্রিন ডকুমেন্ট খুঁজে পেতে 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-এর আগে: অফস্ক্রিন ডকুমেন্ট খোলা আছে কিনা চেক করুন

Chrome 116-এ runtime.getContexts() যোগ করা হয়েছে। 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>