chrome.offscreen

תיאור

הרשאות

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

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

זמינות

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

ל-Service Workers אין גישה ל-DOM, ואתרים רבים כוללים מדיניות אבטחת תוכן שמגבילה את הפונקציונליות של סקריפטים של תוכן. ה-API הלא-מסך מאפשר לתוסף להשתמש בממשקי DOM API במסמך מוסתר בלי להפריע לחוויית המשתמש על ידי פתיחה של כרטיסיות או חלונות חדשים. ה-API של runtime הוא ה-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.

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

המכשיר 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,
)