chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

tabCapture

نظرة عامة

تتيح لك واجهة برمجة التطبيقات chrome.tabCapture API الوصول إلى 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

الإصدار 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(
  callback?: function,
): Promise<CaptureInfo[]>

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

المعلمات

  • callback

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

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

    (result: CaptureInfo[]) => void

المرتجعات

  • Promise<CaptureInfo[]>

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

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

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

getMediaStreamId()

Promise Chrome 71 والإصدارات الأحدث 
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