chrome.offscreen

תיאור

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

הרשאות

offscreen

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

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

זמינות

Chrome 109+ MV3+

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

לעובדי שירות אין גישת 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);
    });
  }
}

סוגים

CreateParameters

מאפיינים

• הצדקה

  מחרוזת

  מחרוזת שסופקה על ידי המפתח, שמסבירה בפירוט רב יותר את הצורך בהקשר של הרקע. סוכן המשתמש _עשוי_ להשתמש בערך הזה בתצוגה למשתמש.

• סיבות

  הסיבה[]

  הסיבה או הסיבות לכך שהתוסף יוצר את המסמך שלא מוצג במסך.

• כתובת אתר

  מחרוזת

  כתובת ה-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"
ההגדרה קובעת שהמסמך מחוץ למסך צריך להשתמש בממשקי API של WebRTC.

"CLIPboard"
מציין שהמסמך מחוץ למסך צריך לפעול עם ה-API של הלוח.

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

"WORKERS"
מציין שהמסמך צריך להיות מחוץ למסך כדי להציג עובדים.

"BATTERY_STATUS"
מציין שבמסמך שלא נמצא במסך צריך להשתמש ב-navigator.getBattery.

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

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

שיטות

closeDocument()

הבטחה

chrome.offscreen.closeDocument(
  callback?: function,
)

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

פרמטרים

• קריאה חוזרת (callback)

  פונקציה אופציונלית

  הפרמטר callback נראה כך:

  () => void

החזרות

• הבטחה<Empty>

  הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

createDocument()

הבטחה

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

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

פרמטרים

• פרמטרים

  CreateParameters

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

• קריאה חוזרת (callback)

  פונקציה אופציונלית

  הפרמטר callback נראה כך:

  () => void

החזרות

• הבטחה<Empty>

  הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.