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

מאפיינים

• מסך מלא

  בוליאני

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

• status

  TabCaptureState

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

• tabId

  number

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

CaptureOptions

מאפיינים

• אודיו

  boolean אופציונלי

• audioConstraints

  ‫MediaStreamConstraint אופציונלי

• סרטון

  boolean אופציונלי

• videoConstraints

  ‫MediaStreamConstraint אופציונלי

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()

chrome.tabCapture.getCapturedTabs(): Promise<CaptureInfo[]>

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

החזרות

• Promise<CaptureInfo[]>

  ‫Chrome 116 ואילך

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

getMediaStreamId()

‫Chrome 71 ואילך

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

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

פרמטרים

• options

  ‫GetMediaStreamOptions optional

החזרות

• Promise<string>

  ‫Chrome 116 ואילך

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

אירועים

onStatusChanged

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

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

פרמטרים

• callback

  פונקציה

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

  (info: CaptureInfo) => void

  • מידע

    CaptureInfo