chrome.offscreen

תיאור

הרשאות

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

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

זמינות

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

ל-Service Workers אין גישה ל-DOM, ובאתרים רבים יש מדיניות אבטחת תוכן שמגבילה את הפונקציונליות של סקריפטים של תוכן. ה-API של Offscreen מאפשר לתוסף להשתמש בממשקי 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 ו-offscreen-dom ב-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 matchedClients.some(client => {
      return client.url.includes(chrome.runtime.id);
    });
  }
}

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

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