browser.tabCapture

الوصف

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

الأذونات

tabCapture

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

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

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

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

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

const output = new AudioContext();
const source = output.createMediaStreamSource(stream);
source.connect(output.destination);

يؤدي ذلك إلى إنشاء AudioContext جديد وربط الصوت الصادر من علامة التبويب MediaStream بوجهة البث التلقائية.

معرّفات مصادر البيانات

سيؤدي طلب browser.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، كان معرّف البث محصورًا بكل من مصدر الأمان وعملية العرض وإطار العرض الخاصين بالمتصل.

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

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

الأنواع

CaptureInfo

الخصائص

  • ملء الشاشة

    قيمة منطقية

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

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

  • tabId

    الرقم

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

CaptureOptions

الخصائص

GetMediaStreamOptions

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

الخصائص

  • consumerTabId

    number اختياري

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

  • targetTabId

    number اختياري

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

MediaStreamConstraint

الخصائص

  • إلزامي

    عنصر

  • اختياري

    كائن اختياري

TabCaptureState

تعداد

"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(): Promise<CaptureInfo[]>

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

المرتجعات

  • Promise<CaptureInfo[]>

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

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

getMediaStreamId()

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

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

المعلمات

المرتجعات

  • Promise<string>

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

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

الفعاليات

onStatusChanged

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

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

المعلمات

  • callback

    دالة

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

    (info: CaptureInfo) => void