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

الخصائص

• ملء الشاشة

  قيمة منطقية

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

• status

  TabCaptureState

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

• tabId

  الرقم

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

CaptureOptions

الخصائص

• بعدّة لغات"

  boolean اختياري

• audioConstraints

  ‫MediaStreamConstraint اختياري

• فيديو

  boolean اختياري

• videoConstraints

  ‫MediaStreamConstraint اختياري

GetMediaStreamOptions

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

الخصائص

• 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

  • نتيجة

    CaptureInfo[]

المرتجعات

• Promise<CaptureInfo[]>

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

  تعرض هذه الطريقة Promise يتم تنفيذه باستخدام CaptureInfo[] لعلامات التبويب التي تم التقاطها.

  لا تتوفّر الوعود إلا في الإصدار 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 والإصدارات الأحدث

  تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة. في حال النجاح، تكون النتيجة عبارة عن سلسلة مبهمة يمكن تمريرها إلى واجهة برمجة التطبيقات getUserMedia() لإنشاء بث وسائط يتوافق مع علامة التبويب المستهدَفة. لا يمكن استخدام streamId الذي تم إنشاؤه إلا مرة واحدة وتنتهي صلاحيته بعد بضع ثوانٍ إذا لم يتم استخدامه.

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

الفعاليات

onStatusChanged

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

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

المعلمات

• callback

  دالة

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

  (info: CaptureInfo) => void

  • معلومات

    CaptureInfo