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

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

الخصائص

  • 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(
  callback?: function,
): Promise<CaptureInfo[]>

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

المعلمات

  • callback

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

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

    (result: CaptureInfo[]) => void

المرتجعات

  • 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