chrome.offscreen

תיאור

הרשאות

כדי להשתמש ב-Offscreen API, צריך להצהיר על ההרשאה "offscreen" במניפסט של התוסף. לדוגמה:

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

זמינות

מושגים ושימוש

לעובדי שירות אין גישת DOM, ובאתרים רבים יש מדיניות אבטחת תוכן להגביל את הפונקציונליות של סקריפטים של תוכן. ה-Offscreen API מאפשר לתוסף להשתמש ב-DOM ממשקי API במסמך מוסתר מבלי להפריע לחוויית המשתמש על ידי פתיחת חלונות חדשים או כרטיסיות. runtime API הוא ה-API היחיד של תוספים שנתמכות על ידי מסמכים מחוץ למסך.

טיפול בדפים שנטענים כמסמכים מחוץ למסך שונה מזה של סוגים אחרים של דפי תוספים. ההרשאות של התוסף עוברות למסמכים מחוץ למסך, אבל עם הגבלות על ה-API של התוסף גישה. לדוגמה, כי ה-API של chrome.runtime הוא ממשקי API של תוספים שנתמכים על ידי מסמכים מחוץ למסך, חייבים לטפל בהעברת ההודעות באמצעות חברים באותו API.

הנה דרכים נוספות שבהן מסמכים מחוץ למסך מתנהגים באופן שונה מדפים רגילים:

• כתובת ה-URL של מסמך שנמצא מחוץ למסך חייבת להיות קובץ HTML סטטי בחבילה עם התוסף.
• לא ניתן להתמקד במסמכים שלא מופיעים במסך.
• מסמך שלא מופיע במסך הוא מופע של 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: '...'
  });
});

לקבלת דוגמאות שלמות אפשר לעיין בoffscreen-clipboard הדגמות של off-screen ב-GitHub.

לפני Chrome 116: איך בודקים אם מסמך שלא נמצא במסך פתוח

runtime.getContexts() נוסף בגרסה 116 של Chrome. בגרסאות קודמות של 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,
)