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

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

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

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

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

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

אירועים

onStatusChanged

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

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

פרמטרים

  • callback

    פונקציה

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

    (info: CaptureInfo) => void