chrome.offscreen

תיאור

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

הרשאות

offscreen

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

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

זמינות

‫Chrome 109 ואילך MV3 ואילך

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

ל-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);
    });
  }
}

סוגים

CreateParameters

מאפיינים

• הצדקה

  מחרוזת

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

• סיבות

  Reason[]

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

• כתובת אתר

  מחרוזת

  כתובת ה-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()

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

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

החזרות

• Promise<void>

  הבטחה שמושלמת כשמסמך מחוץ למסך נסגר.

createDocument()

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

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

פרמטרים

• פרמטרים

  CreateParameters

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

החזרות

• Promise<void>

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