chrome.tabCapture

الوصف

استخدِم واجهة برمجة التطبيقات chrome.tabCapture للتفاعل مع وسائط علامات التبويب.

الأذونات

tabCapture

نظرة عامة

تتيح لك واجهة برمجة التطبيقات chrome.tabCapture الوصول إلى MediaStream الذي يحتوي على فيديو وصوت من علامة التبويب الحالية. لا يمكن استدعاء هذه الدالة إلا بعد أن يستدعي المستخدم إضافة، مثلاً من خلال النقر على زر الإجراء الخاص بالإضافة. وهذا مشابه لسلوك إذن activeTab.

الحفاظ على صوت النظام

عند الحصول على MediaStream لعلامة تبويب، لن يتم تشغيل الصوت في علامة التبويب هذه للمستخدم. يشبه ذلك سلوك الدالة getDisplayMedia() عندما يتم ضبط العلامة suppressLocalAudioPlayback على "صحيح".

لمواصلة تشغيل الصوت للمستخدم، استخدِم ما يلي:

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. وهذا يعني أنّه يمكن استخدام معرّف مصدر البيانات الذي تم الحصول عليه في عامل الخدمة في مستند خارج الشاشة.

قبل الإصدار 116 من Chrome، عندما لم يتم تحديد consumerTabId، كان معرّف البث محصورًا بكل من مصدر الأمان وعملية العرض وإطار العرض الخاصين بالمتصل.

مزيد من المعلومات

لمزيد من المعلومات حول كيفية استخدام واجهة برمجة التطبيقات chrome.tabCapture، يُرجى الاطّلاع على تسجيل الصوت والتقاط الشاشة. يوضّح هذا المستند كيفية استخدام tabCapture وواجهات برمجة التطبيقات ذات الصلة لحل عدد من حالات الاستخدام الشائعة.

الأنواع

CaptureInfo

الخصائص

  • ملء الشاشة

    قيمة منطقية

    تُستخدَم لتحديد ما إذا كان أحد العناصر في علامة التبويب التي يتم تسجيلها في وضع ملء الشاشة.

  • حالة الالتقاط الجديدة لعلامة التبويب

  • tabId

    الرقم

    معرّف علامة التبويب التي تغيّرت حالتها.

CaptureOptions

الخصائص

GetMediaStreamOptions

الإصدار 71 من Chrome أو إصدار أحدث

الخصائص

  • consumerTabId

    number اختياري

    المعرّف الاختياري لعلامة التبويب التي ستستدعي getUserMedia() لاحقًا لاستهلاك البث. في حال عدم تحديد ذلك، يمكن للإضافة التي تجري الاتصال فقط استخدام النتيجة. لا يمكن استخدام البث إلا من خلال إطارات في علامة التبويب المحدّدة يتطابق مصدر أمانها مع مصدر علامة تبويب المستهلك. يجب أن يكون مصدر علامة التبويب مصدرًا آمنًا، مثل HTTPS.

  • targetTabId

    number اختياري

    المعرّف الاختياري لعلامة التبويب التي سيتم تسجيلها في حال عدم تحديد علامة التبويب، سيتم اختيار علامة التبويب النشطة الحالية. يمكن استخدام علامات التبويب التي تم منح الإضافة إذن activeTab لها فقط كعلامة تبويب مستهدَفة.

MediaStreamConstraint

الخصائص

  • إلزامي

    عنصر

  • اختياري

    العنصر اختياري

TabCaptureState

Enum

"pending"

"active"

"stopped"

"error"

الطُرق

capture()

في المقدّمة فقط 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

تتيح لك التقاط المنطقة المرئية من علامة التبويب النشطة حاليًا. لا يمكن بدء عملية الالتقاط إلا في علامة التبويب النشطة حاليًا بعد استدعاء الإضافة، على غرار طريقة عمل activeTab. يتم الاحتفاظ بعملية التسجيل عند التنقّل بين الصفحات داخل علامة التبويب، وتتوقف عند إغلاق علامة التبويب أو عند إغلاق بث الوسائط بواسطة الإضافة.

المعلمات

  • الخيارات

    CaptureOptions

    تضبط هذه السمة مصدر وسائط تم إرجاعه.

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (stream: LocalMediaStream) => void

    • البث

      LocalMediaStream

getCapturedTabs()

الوعد 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

تعرِض هذه الطريقة قائمة بعلامات التبويب التي طلبت تسجيل الشاشة أو يتم تسجيلها حاليًا، أي الحالة != متوقف والحالة != خطأ. يسمح ذلك للإضافات بإبلاغ المستخدم بأنّ هناك عملية حالية لالتقاط علامة تبويب ستمنع نجاح عملية جديدة لالتقاط علامة تبويب (أو لمنع الطلبات المكرّرة لعلامة التبويب نفسها).

المعلمات

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (result: CaptureInfo[]) => void

المرتجعات

  • Promise<CaptureInfo[]>

    الإصدار 116 من Chrome والإصدارات الأحدث

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

getMediaStreamId()

Promise الإصدار 71 من Chrome والإصدارات الأحدث 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

تنشئ هذه الدالة معرّف بث لتسجيل علامة التبويب المستهدَفة. تشبه هذه الطريقة طريقة chrome.tabCapture.capture()، ولكنّها تعرض معرّف بث وسائط بدلاً من بث وسائط في علامة التبويب المستهلكة.

المعلمات

  • الخيارات

    GetMediaStreamOptions اختياري

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (streamId: string) => void

    • streamId

      سلسلة

المرتجعات

  • Promise<string>

    الإصدار 116 من Chrome والإصدارات الأحدث

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

الفعاليات

onStatusChanged

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

يتم إطلاق هذا الحدث عند تغيير حالة تسجيل شاشة علامة تبويب. يسمح ذلك لمطوّري الإضافات بتتبُّع حالة تسجيل علامات التبويب من أجل إبقاء عناصر واجهة المستخدم، مثل إجراءات الصفحة، متزامنة.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (info: CaptureInfo) => void