browser.offscreen

বিবরণ

অফস্ক্রিন ডকুমেন্ট তৈরি ও ম্যানেজ করতে offscreen API ব্যবহার করুন।

অনুমতি

offscreen

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

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

উপলভ্যতা

Chrome 109+ ব্রাউজার।* Chrome 148 থেকে MV3+

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

সার্ভিস ওয়ার্কারদের DOM অ্যাক্সেস থাকে না এবং অনেক ওয়েবসাইটের কন্টেন্ট নিরাপত্তা নীতি থাকে যা কন্টেন্ট স্ক্রিপ্টের কার্যকারিতা সীমিত করে। Offscreen 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-এর আগে: অফস্ক্রিন ডকুমেন্ট খোলা আছে কিনা তা চেক করুন

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);
    });
  }
}

ধরন

CreateParameters

প্রপার্টি

• যুক্তি

  স্ট্রিং

  ডেভেলপারের দেওয়া স্ট্রিং যা ব্যাকগ্রাউন্ড কনটেক্সটের প্রয়োজনীয়তা আরও বিস্তারিতভাবে ব্যাখ্যা করে। ব্যবহারকারীকে দেখানোর জন্য ইউজার এজেন্ট এটি ব্যবহার করতে _পারে_।

• কারণ

  কারণ[]

  যে কারণে এক্সটেনশন অফস্ক্রিন ডকুমেন্ট তৈরি করছে।

• URL

  স্ট্রিং

  ডকুমেন্টে লোড করার জন্য (রিলেটিভ) URL।

Reason

Enum

"পরীক্ষা করা হচ্ছে"
শুধু পরীক্ষা করার জন্য ব্যবহার করা কারণ।

"AUDIO_PLAYBACK"
অফস্ক্রিন ডকুমেন্ট যে অডিও চালানোর জন্য দায়ী তা নির্দিষ্ট করে।

"IFRAME_SCRIPTING"
নির্দিষ্ট করে যে অফস্ক্রিন ডকুমেন্টকে iframe-এর কন্টেন্ট পরিবর্তন করার জন্য একটি iframe এম্বেড এবং স্ক্রিপ্ট করতে হবে।

"DOM_SCRAPING"
নির্দিষ্ট করে যে অফস্ক্রিন ডকুমেন্টে একটি iframe এম্বেড করতে হবে এবং তথ্য এক্সট্র্যাক্ট করার জন্য এর DOM স্ক্র্যাপ করতে হবে।

"BLOBS"
অফস্ক্রিন ডকুমেন্টকে Blob অবজেক্টের (URL.createObjectURL() সহ) সাথে ইন্টার‍্যাক্ট করতে হবে বলে উল্লেখ করে।

"DOM_PARSER"
অফস্ক্রিন ডকুমেন্টকে DOMParser API ব্যবহার করতে হবে বলে উল্লেখ করে।

"USER_MEDIA"
অফস্ক্রিন ডকুমেন্টকে ব্যবহারকারীর মিডিয়া (যেমন, getUserMedia()) থেকে মিডিয়া স্ট্রিমের সাথে ইন্টার‍্যাক্ট করতে হবে বলে নির্দিষ্ট করে।

"DISPLAY_MEDIA"
নির্দিষ্ট করে যে অফস্ক্রিন ডকুমেন্টকে ডিসপ্লে মিডিয়া (যেমন, getDisplayMedia()) থেকে মিডিয়া স্ট্রিমের সাথে ইন্টার‍্যাক্ট করতে হবে।

"WEB_RTC"
অফস্ক্রিন ডকুমেন্টকে যে WebRTC API ব্যবহার করতে হবে তা নির্দিষ্ট করে।

"ক্লিপবোর্ড"
নির্দিষ্ট করে যে অফস্ক্রিন ডকুমেন্টকে ক্লিপবোর্ড API-এর সাথে ইন্টার‍্যাক্ট করতে হবে।

"LOCAL_STORAGE"
অফস্ক্রিন ডকুমেন্টের localStorage-এ অ্যাক্সেস প্রয়োজন তা নির্দিষ্ট করে।

"WORKERS"
অফস্ক্রিন ডকুমেন্টকে যে ওয়ার্কার স্পন করতে হবে তা নির্দিষ্ট করে।

"BATTERY_STATUS"
অফস্ক্রিন ডকুমেন্টকে যে navigator.getBattery ব্যবহার করতে হবে তা নির্দিষ্ট করে।

"MATCH_MEDIA"
অফস্ক্রিন ডকুমেন্টকে যে window.matchMedia ব্যবহার করতে হবে তা নির্দিষ্ট করে।

"GEOLOCATION"
অফস্ক্রিন ডকুমেন্টকে navigator.geolocation ব্যবহার করতে হবে বলে উল্লেখ করে।

পদ্ধতি

closeDocument()

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

এক্সটেনশনের জন্য বর্তমানে খোলা অফস্ক্রিন ডকুমেন্ট বন্ধ করে।

রিটার্ন

• <void> প্রমিস

  অফস্ক্রিন ডকুমেন্ট বন্ধ হয়ে গেলে প্রমিস রিজলভ হয়।

createDocument()

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

এক্সটেনশনের জন্য একটি নতুন অফস্ক্রিন ডকুমেন্ট তৈরি করে।

প্যারামিটারগুলি

• parameters

  CreateParameters

  অফস্ক্রিন ডকুমেন্ট তৈরি করার জন্য প্যারামিটার।

রিটার্ন

• <void> প্রমিস

  অফস্ক্রিন ডকুমেন্ট তৈরি হয়ে গেলে এবং প্রাথমিক পৃষ্ঠা লোড সম্পূর্ণ হলে প্রমিস রিজলভ হয়।

hasDocument()

Chrome 150+

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

এক্সটেনশনে কোনও অ্যাক্টিভ ডকুমেন্ট আছে কিনা তা নির্ধারণ করে।

রিটার্ন

• Promise<boolean>

  এক্সটেনশনে কোনও অ্যাক্টিভ অফস্ক্রিন ডকুমেন্ট আছে কিনা সেই ফলাফল সহ প্রমিস সমাধান করে।