chrome.tabCapture

תיאור

משתמשים ב-chrome.tabCapture API כדי ליצור אינטראקציה עם מדיה שמוזרמת מכרטיסיות.

הרשאות

tabCapture

סקירה כללית

ממשק ה-API של chrome.tabCapture מאפשר לכם לגשת ל-MediaStream שמכיל סרטון ואודיו של הכרטיסייה הנוכחית. אפשר להפעיל את הפונקציה הזו רק אחרי שהמשתמש מפעיל תוסף, למשל על ידי לחיצה על לחצן הפעולה של התוסף. ההתנהגות הזו דומה להתנהגות של ההרשאה activeTab.

שמירה של אודיו מהמערכת

כשמתקבל MediaStream לכרטיסייה, האודיו בכרטיסייה הזו לא יושמע יותר למשתמש. ההתנהגות הזו דומה להתנהגות של הפונקציה getDisplayMedia() כשהדגל suppressLocalAudioPlayback מוגדר כ-True.

כדי להמשיך להפעיל אודיו למשתמש, צריך להשתמש בפקודות הבאות:

const output = new AudioContext();
const source = output.createMediaStreamSource(stream);
source.connect(output.destination);

כך נוצר AudioContext חדש והשמע של MediaStream בכרטיסייה מחובר ליעד ברירת המחדל.

מזהי מקורות נתונים

התקשרות אל chrome.tabCapture.getMediaStreamId תחזיר מזהה של מקור נתונים. כדי לגשת מאוחר יותר ל-MediaStream מהמזהה, משתמשים בפעולות הבאות:

navigator.mediaDevices.getUserMedia({
  audio: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
  video: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
});

הגבלות שימוש

אחרי שמתקשרים אל getMediaStreamId(), יש הגבלות על המקומות שבהם אפשר להשתמש במזהה המקור שמוחזר:

  • אם מציינים את consumerTabId, אפשר להשתמש במזהה בקריאה ל-getUserMedia() בכל פריים בכרטיסייה הנתונה שיש לו אותו מקור אבטחה.
  • אם לא מציינים את המזהה, החל מגרסה Chrome 116, אפשר להשתמש בו בכל מסגרת עם אותו מקור אבטחה באותו תהליך עיבוד כמו הקורא. כלומר, אפשר להשתמש במזהה מקור נתונים שהתקבל ב-service worker במסמך שלא מוצג במסך.

לפני Chrome 116, אם לא צוין consumerTabId, מזהה הסטרים הוגבל למקור האבטחה, לתהליך העיבוד ולמסגרת העיבוד של המתקשר.

מידע נוסף

מידע נוסף על השימוש ב-API של chrome.tabCapture זמין במאמר הקלטת אודיו וצילום מסך. בדוגמאות האלה נראה איך משתמשים ב-tabCapture ובממשקי API קשורים כדי לפתור כמה תרחישים נפוצים.

סוגים

CaptureInfo

מאפיינים

  • מסך מלא

    בוליאני

    האם רכיב בכרטיסייה שמתבצעת ממנה לכידה נמצא במצב מסך מלא.

  • סטטוס הצילום החדש של הכרטיסייה.

  • tabId

    number

    המזהה של הכרטיסייה שהסטטוס שלה השתנה.

CaptureOptions

מאפיינים

GetMediaStreamOptions

‫Chrome 71 ואילך

מאפיינים

  • consumerTabId

    מספר אופציונלי

    מזהה הכרטיסייה האופציונלי של הכרטיסייה שתפעיל בהמשך את getUserMedia() כדי לצרוך את הסטרימינג. אם לא מציינים את הזרם, אפשר להשתמש בו רק בתוסף שקורא לו. אפשר להשתמש בזרם רק בפריימים בכרטיסייה הנתונה, שמקור האבטחה שלהם תואם למקור של כרטיסיית הצרכן. המקור של הכרטיסייה חייב להיות מקור מאובטח, למשל HTTPS.

  • targetTabId

    מספר אופציונלי

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

MediaStreamConstraint

מאפיינים

  • חובה

    אובייקט

  • אופציונלי

    אובייקט אופציונלי

TabCaptureState

Enum

‫"pending"

‫'active'

‫"stopped"

"error"

Methods

capture()

רק בחזית 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

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

פרמטרים

  • options

    CaptureOptions

    הגדרת זרם המדיה שמוחזר.

  • callback

    פונקציה

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

    (stream: LocalMediaStream) => void

    • זרם

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

מחזירה רשימה של כרטיסיות שנשלחה לגביהן בקשה לצילום או שהן מצולמות, כלומר status != stopped ו-status != error. כך התוספים יכולים ליידע את המשתמש שיש צילום כרטיסייה קיים שימנע מצילום כרטיסייה חדש להצליח (או למנוע בקשות מיותרות לאותה כרטיסייה).

פרמטרים

  • callback

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

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

    (result: CaptureInfo[]) => void

החזרות

  • Promise<CaptureInfo[]>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getMediaStreamId()

Promise Chrome 71 ואילך 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

יוצר מזהה של מקור נתונים כדי ללכוד את כרטיסיית היעד. בדומה לשיטה chrome.tabCapture.capture(), אבל מחזירה מזהה של סטרימינג מדיה, במקום סטרימינג מדיה, לכרטיסיית הצרכן.

פרמטרים

  • options

    ‫GetMediaStreamOptions optional

  • callback

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

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

    (streamId: string) => void

    • streamId

      מחרוזת

החזרות

  • Promise<string>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

אירועים

onStatusChanged

chrome.tabCapture.onStatusChanged.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

    (info: CaptureInfo) => void