chrome.tabCapture

תיאור

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

הרשאות

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() בכל מסגרת ב- כרטיסייה נתונה עם אותו מקור אבטחה.
  • אם המדיניות לא מוגדרת, החל מגרסה 116 של Chrome, אפשר להשתמש במזהה בכל מסגרת עם אותו מקור אבטחה באותו תהליך עיבוד כמו מבצע הקריאה החוזרת. פירוש הדבר הוא שמזהה מקור הנתונים התקבל. ב-Service Worker אפשר להשתמש במסמך offscreen.

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

מידע נוסף

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

סוגים

CaptureInfo

מאפיינים

  • מסך מלא

    בוליאני

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

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

  • tabId

    number

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

CaptureOptions

מאפיינים

  • אודיו

    ערך בוליאני אופציונלי

  • audioConstraints

    MediaStreamConstraint אופציונלי

  • סרטון

    ערך בוליאני אופציונלי

  • videoConstraints

    MediaStreamConstraint אופציונלי

GetMediaStreamOptions

Chrome מגרסה 71 ואילך

מאפיינים

  • consumerTabId

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

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

  • targetTabId

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

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

MediaStreamConstraint

מאפיינים

  • חובה

    אובייקט

  • אופציונלי

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

TabCaptureState

Enum

"בהמתנה"

"פעיל"

"sהופסק"

"שגיאה"

שיטות

capture()

חזית בלבד 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

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

פרמטרים

  • אפשרויות

    CaptureOptions

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

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

    פונקציה

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

    (stream: LocalMediaStream) => void

    • זרם

      LocalMediaStream

getCapturedTabs()

הבטחה 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

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

פרמטרים

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

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

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

    (result: CaptureInfo[]) => void

החזרות

  • Promise<CaptureInfo[]>

    Chrome 116 ואילך

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

getMediaStreamId()

הבטחה Chrome מגרסה 71 ואילך 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    GetMediaStreamOptions אופציונלית

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

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

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

    (streamId: string) => void

    • streamId

      מחרוזת

החזרות

  • Promise<string>

    Chrome 116 ואילך

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

אירועים

onStatusChanged

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

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

פרמטרים

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

    פונקציה

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

    (info: CaptureInfo) => void