chrome.tabCapture

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

משתמשים ב-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

ספירה

'בהמתנה'

'פעיל'

'הופסק'

‫"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 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getMediaStreamId()

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

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

פרמטרים

  • options

    ‫GetMediaStreamOptions אופציונלי

  • callback

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

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

    (streamId: string) => void

    • streamId

      מחרוזת

החזרות

  • Promise<string>

    ‫Chrome 116 ואילך

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

onStatusChanged

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

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

פרמטרים

  • callback

    פונקציה

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

    (info: CaptureInfo) => void