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()، هناك قيود على الأماكن التي يمكن فيها استخدام معرّف مصدر البيانات الذي تم عرضه:

  • If consumerTabId is specified, the ID can be used by a getUserMedia() call in any frame in the given tab which has the same security origin.
  • في حال عدم تحديد ذلك، يمكن استخدام رقم التعريف في أي إطار له مصدر الأمان نفسه في عملية العارض نفسها التي يستخدمها المتصل، وذلك اعتبارًا من الإصدار 116 من Chrome. وهذا يعني أنّه يمكن استخدام معرّف البث الذي تم الحصول عليه في مشغّل الخدمات في مستند خارج الشاشة.

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

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

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

الأنواع

CaptureInfo

الخصائص

  • ملء الشاشة

    قيمة منطقية

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

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

  • tabId

    الرقم

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

CaptureOptions

الخصائص

  • ملف صوتي

    قيمة منطقية اختيارية

  • audioConstraints

    MediaStreamConstraint اختياري

  • فيديو

    قيمة منطقية اختيارية

  • videoConstraints

    MediaStreamConstraint اختياري

GetMediaStreamOptions

الإصدار 71 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • consumerTabId

    number اختيارية

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

  • targetTabId

    number اختيارية

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

MediaStreamConstraint

الخصائص

  • إلزامي

    عنصر

  • اختياري

    object اختياري

TabCaptureState

Enum

"pending"

"active"

"stopped"

"error"

الطُرق

capture()

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

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

المعلمات

  • الخيارات

    CaptureOptions

    لضبط مصدر الوسائط الذي يتم عرضه

  • callback

    دالة

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

    (stream: LocalMediaStream) => void

    • البث

      LocalMediaStream

getCapturedTabs()

browser.tabCapture.getCapturedTabs(): Promise<CaptureInfo[]>

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

المرتجعات

  • Promise<CaptureInfo[]>

    الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

getMediaStreamId()

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

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

المعلمات

المرتجعات

  • وعد<سلسلة>

    الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

الفعاليات

onStatusChanged

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

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

المعلمات

  • callback

    دالة

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

    (info: CaptureInfo) => void