chrome.tabCapture

الوصف

استخدام chrome.tabCapture API للتفاعل مع ساحات مشاركات الوسائط في علامات التبويب

الأذونات

tabCapture

المفاهيم والاستخدام

تتيح لك واجهة برمجة التطبيقات chrome.tabCapture API الوصول إلى 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، يمكن استخدام المعرّف في أي إطار وبأصل الأمان نفسه في عملية العرض نفسها مثل المتصل. هذا يعني أنّه يمكن استخدام رقم تعريف مصدر البيانات الذي تم الحصول عليه في مشغّل الخدمات في مستند خارج الشاشة.

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

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

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

الأنواع

CaptureInfo

أماكن إقامة

  • ملء الشاشة

    boolean

    تحدّد هذه السمة ما إذا كان العنصر في علامة التبويب التي يتم التقاطها في وضع ملء الشاشة.

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

  • tabId

    الرقم

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

CaptureOptions

أماكن إقامة

GetMediaStreamOptions

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

أماكن إقامة

  • consumerTabId

    الرقم اختياري

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

  • targetTabId

    الرقم اختياري

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

MediaStreamConstraint

أماكن إقامة

  • إلزامي

    كائن

  • إجراء اختياري

    الكائن اختياري

TabCaptureState

التعداد

الطُرق

capture()

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

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

المَعلمات

  • الخيارات

    CaptureOptions

    تحدِّد هذه السياسة بث الوسائط التي يتم عرضها.

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (stream: LocalMediaStream)=>void

    • البث

      LocalMediaStream

getCapturedTabs()

وعد 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (result: CaptureInfo[])=>void

المرتجعات

  • Promise<CaptureInfo[]>

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

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getMediaStreamId()

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

تُنشئ معرّف مصدر لتسجيل علامة التبويب المستهدفة. يشبه طريقة chrome.tabCapture.capture() ، ولكنه يعرض رقم تعريف مصدر بيانات الوسائط، بدلاً من مصدر بيانات الوسائط، إلى علامة تبويب "المستهلك".

المَعلمات

  • الخيارات

    GetMediaStreamOptions اختيارية

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (streamId: string)=>void

    • streamId

      سلسلة

المرتجعات

  • وعد<string>

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

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

فعاليات

onStatusChanged

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (info: CaptureInfo)=>void