browser.offscreen

תיאור

משתמשים ב-API של offscreen כדי ליצור ולנהל מסמכים מחוץ למסך.

הרשאות

offscreen

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

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

זמינות

‫Chrome 109 ואילך ‫browser.* ‎ מגרסה Chrome 148 ‫MV3 ואילך

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

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

דפים שנטענים כמסמכים מחוץ למסך מטופלים באופן שונה מסוגים אחרים של דפי תוספים. ההרשאות של התוסף עוברות למסמכים מחוץ למסך, אבל עם מגבלות על הגישה ל-API של התוסף. לדוגמה, מכיוון ש-API של browser.runtime הוא ה-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 מגדירה את סגירת המסמך אחרי 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 = 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: '...'
  });
});

דוגמאות מלאות זמינות בהדגמות של offscreen-clipboard ו-offscreen-dom ב-GitHub.

לפני 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)

‫"TESTING"
סיבה שמשמשת למטרות בדיקה בלבד.

"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 APIs.

"CLIPBOARD"
מציין שהמסמך מחוץ למסך צריך לקיים אינטראקציה עם Clipboard API.

"LOCAL_STORAGE"
מציין שהמסמך מחוץ למסך צריך גישה אל localStorage.

"WORKERS"
מציין שהמסמך מחוץ למסך צריך להפעיל קובצי Worker.

‫"BATTERY_STATUS"
מציין שהמסמך מחוץ למסך צריך להשתמש ב-navigator.getBattery.

"MATCH_MEDIA"
מציין שהמסמך מחוץ למסך צריך להשתמש ב-window.matchMedia.

‫"GEOLOCATION"
מציין שהמסמך מחוץ למסך צריך להשתמש ב-navigator.geolocation.

Methods

closeDocument()

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

סגירת המסמך שפתוח כרגע מחוץ למסך של התוסף.

החזרות

• Promise<void>

  אובייקט Promise שמופעל כשהמסמך מחוץ למסך נסגר.

createDocument()

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

יצירת מסמך חדש מחוץ למסך בשביל התוסף.

פרמטרים

• פרמטרים

  CreateParameters

  הפרמטרים שמתארים את המסמך מחוץ למסך שרוצים ליצור.

החזרות

• Promise<void>

  הבטחה שמתקיימת כשהמסמך מחוץ למסך נוצר וטעינת הדף הראשונית שלו הושלמה.

hasDocument()

‫Chrome מגרסה 150 ואילך

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

קובע אם לתוסף יש מסמך פעיל.

החזרות

• Promise<boolean>

  אובייקט Promise שמוחזר עם התוצאה אם לתוסף יש מסמך פעיל מחוץ למסך.