chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

תיאור

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

הרשאות

tabCapture

ההרשאה הזו מפעילה אזהרה.

סקירה כללית

באמצעות chrome.tabCapture API אפשר לגשת ל-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

מאפיינים

• מסך מלא

  בוליאני

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

• status

  TabCaptureState

  סטטוס ההקלטה החדש של הכרטיסייה.

• tabId

  number

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

CaptureOptions

מאפיינים

• אודיו

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

• audioConstraints

  MediaStreamConstraint אופציונלי

• סרטון

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

• videoConstraints

  MediaStreamConstraint אופציונלי

GetMediaStreamOptions

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

מאפיינים

• consumerTabId

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

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

• targetTabId

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

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

MediaStreamConstraint

מאפיינים

• חובה

  אובייקט

• אופציונלי

  object optional

TabCaptureState

טיפוסים בני מנייה (enum)

"בהמתנה"

"active"

"stopped"

"error"

Methods

capture()

חזית בלבד

chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

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

פרמטרים

• אפשרויות

  CaptureOptions

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

• callback

  פונקציה

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

  (stream: LocalMediaStream) => void

  • זרם

    LocalMediaStream

getCapturedTabs()

Promise

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

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

פרמטרים

• callback

  function optional

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

  (result: CaptureInfo[]) => void

  • תוצאה

    CaptureInfo[]‎

החזרות

• Promise<CaptureInfo[]>

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

  מחזירה Promise שמתקבל עם CaptureInfo[] ‎ לכרטיסיות שצולמו.

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getMediaStreamId()

Promise Chrome 71 ואילך

chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

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

פרמטרים

• אפשרויות

  ‫GetMediaStreamOptions אופציונלי

• callback

  function optional

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

  (streamId: string) => void

  • streamId

    מחרוזת

החזרות

• Promise<string>

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

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

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

אירועים

onStatusChanged

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

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

פרמטרים

• callback

  פונקציה

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

  (info: CaptureInfo) => void

  • מידע

    CaptureInfo