الانتقال للأعلى أو للأسفل في علامة التبويب التي تم تسجيلها وتكبيرها أو تصغيرها

François Beaufort
François Beaufort
GitHub
Elad Alon

تتيح واجهة برمجة التطبيقات Screen Capture API مشاركة علامات التبويب والنوافذ والشاشات على منصة الويب. عندما يطلب تطبيق ويب الوصول إلى getDisplayMedia()، يطلب Chrome من المستخدم مشاركة علامة تبويب أو نافذة أو شاشة مع تطبيق الويب كفيديو MediaStreamTrack.

تعرض العديد من تطبيقات الويب التي تستخدم getDisplayMedia() للمستخدم معاينة فيديو للسطح الذي تم التقاطه. على سبيل المثال، غالبًا ما تبث تطبيقات مؤتمرات الفيديو هذا الفيديو إلى المستخدمين البعيدين مع عرضه أيضًا في HTMLVideoElement محلي، لكي يرى المستخدم المحلي باستمرار معاينة لما يشاركه.

تقدّم هذه المستندات واجهة برمجة التطبيقات الجديدة Captured Surface Control API في Chrome، والتي تتيح لتطبيق الويب الخاص بك إمكانية التنقّل في علامة تبويب تم التقاطها، بالإضافة إلى قراءة مستوى التكبير/التصغير وكتابته في علامة تبويب تم التقاطها.

يتنقّل المستخدم ويُكبّر علامة تبويب تم التقاطها (عرض توضيحي).

لماذا يجب استخدام Captured Surface Control؟

تعاني جميع تطبيقات مؤتمرات الفيديو من العيب نفسه. إذا أراد المستخدم التفاعل مع علامة تبويب أو نافذة تم التقاطها، عليه التبديل إلى تلك النافذة، ما يؤدي إلى إخراجه من تطبيق مؤتمرات الفيديو. ويطرح ذلك بعض التحديات:

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

تعالج واجهة برمجة التطبيقات Captured Surface Control API هذه المشاكل.

كيف يمكنني استخدام ميزة "التحكّم في السطح الذي تم التقاطه"؟

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

تسجيل علامة تبويب متصفّح

ابدأ بطلب اختيار سطح للمشاركة باستخدام getDisplayMedia()، وخلال ذلك، اربط عنصر CaptureController بجلسة الالتقاط. سنستخدم هذا العنصر للتحكّم في السطح الذي تم التقاطه قريبًا.

const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });

بعد ذلك، أنشئ معاينة محلية للمساحة التي تم التقاطها في شكل عنصر <video>:

const previewTile = document.querySelector('video');
previewTile.srcObject = stream;

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

const [track] = stream.getVideoTracks();

if (track.getSettings().displaySurface !== 'browser') {
  // Bail out early if the user didn't pick a tab.
  return;
}

طلب الإذن

يؤدي الاستدعاء الأول لأي من forwardWheel() أو increaseZoomLevel() أو decreaseZoomLevel() أو resetZoomLevel() على عنصر CaptureController معيّن إلى ظهور طلب للحصول على إذن. إذا منح المستخدم الإذن، سيُسمح باستدعاء هذه الطرق مرة أخرى.

يجب أن يتفاعل المستخدم مع التطبيق لعرض طلب الحصول على الإذن، لذا يجب ألا يستدعي التطبيق الطرق المذكورة أعلاه إلا إذا كان لديه الإذن مسبقًا أو استجابةً لتفاعل المستخدم، مثل النقر click على زر ذي صلة في تطبيق الويب.

صفحة مواضع التمرير

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

بافتراض أنّ تطبيق الالتقاط يستخدم عنصر <video> باسم "previewTile"، يعرض الرمز التالي كيفية إعادة توجيه أحداث عجلة التمرير إلى علامة التبويب التي تم التقاطها:

const previewTile = document.querySelector('video');
try {
  // Relay the user's action to the captured tab.
  await controller.forwardWheel(previewTile);
} catch (error) {
  // Inspect the error.
  // ...
}

تتلقّى الدالة forwardWheel() إدخالاً واحدًا يمكن أن يكون أحد ما يلي:

  • عنصر HTML سيتم منه إعادة توجيه أحداث عجلة التمرير إلى علامة التبويب التي تم التقاطها.
  • ‫null، ما يشير إلى أنّه يجب إيقاف إعادة التوجيه.

يؤدي طلب ناجح إلى forwardWheel() إلى إلغاء الطلبات السابقة.

يمكن رفض الوعد الذي تعرضه الدالة forwardWheel() في الحالات التالية:

  • إذا لم تبدأ جلسة الالتقاط بعد أو إذا توقّفت.
  • إذا لم يمنح المستخدم الإذن ذي الصلة

Zoom

يتم التفاعل مع مستوى تكبير/تصغير علامة التبويب التي تم التقاطها من خلال مساحات واجهة برمجة التطبيقات CaptureController التالية:

getSupportedZoomLevels()

تعرض هذه الطريقة قائمة بمستويات التكبير/التصغير التي يتيحها المتصفّح لنوع السطح الذي يتم التقاطه. يتم تمثيل القيم في هذه القائمة كنسبة مئوية مقارنةً بـ "مستوى التكبير/التصغير التلقائي"، والذي يتم تحديده على أنّه %100. القائمة تتزايد بشكل رتيب وتحتوي على القيمة 100.

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

يمكن استدعاء controller.getSupportedZoomLevels() في حال استيفاء الشروط التالية:

  • controller مرتبطة بعملية تسجيل نشطة.
  • يتم التقاط علامة تبويب.

سيظهر خطأ في حال عدم توفّرها.

لا يُشترط الحصول على إذن "captured-surface-control" لاستدعاء هذه الطريقة.

zoomLevel

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

بعد انتهاء عملية الالتقاط، ستحتفظ السمة بآخر قيمة لمستوى التكبير/التصغير.

"captured-surface-control" ليس إذنًا غير مطلوب لقراءة هذه السمة.

onzoomlevelchange

يسهّل معالج الأحداث هذا الاستماع إلى التغييرات في مستوى تكبير/تصغير علامة التبويب التي تم التقاطها. ويحدث ذلك في إحدى الحالتين التاليتين:

  • عندما يتفاعل المستخدم مع المتصفّح لتغيير مستوى التكبير/التصغير لعلامة التبويب التي تم التقاطها يدويًا
  • استجابةً لطلبات تطبيق الالتقاط إلى طرق إعدادات التكبير/التصغير (الموضّحة أدناه)

"captured-surface-control" ليس إذنًا غير مطلوب لقراءة هذه السمة.

increaseZoomLevel() وdecreaseZoomLevel() وresetZoomLevel()

تسمح هذه الطرق بالتحكّم في مستوى تكبير علامة التبويب التي تم التقاطها.

يؤدي الضغط على increaseZoomLevel() وdecreaseZoomLevel() إلى تغيير مستوى التكبير/التصغير إلى المستوى التالي أو السابق، على التوالي، وفقًا للترتيب الذي تعرضه getSupportedZoomLevels(). يضبط resetZoomLevel() القيمة على 100.

يجب الحصول على إذن "captured-surface-control" لاستدعاء هذه الطرق. إذا لم يكن لدى تطبيق الالتقاط هذا الإذن، سيُطلب من المستخدم منحه أو رفضه.

تعرض كل هذه الطرق وعدًا يتم تنفيذه إذا كانت المكالمة ناجحة ويتم رفضه في حال عدم نجاحها. تشمل الأسباب المحتملة للرفض ما يلي:

  • الإذن غير متوفّر.
  • تم الاتصال قبل بدء عملية الالتقاط.
  • يتم استدعاء هذه الطريقة بعد انتهاء عملية الالتقاط.
  • تمّت عملية الاستدعاء على controller مرتبطة بعملية تسجيل لنوع سطح عرض غير متوافق. (أي شيء آخر غير التقاط علامة التبويب)
  • محاولات زيادة القيمة أو خفضها إلى ما يتجاوز الحدّ الأقصى أو الأدنى على التوالي

يُنصح بشكل خاص بتجنُّب استدعاء decreaseZoomLevel() إذا كان controller.zoomLevel == controller.getSupportedZoomLevels().at(0)، وحماية عمليات الاستدعاء إلى increaseZoomLevel() بطريقة مشابهة باستخدام .at(-1).

يوضّح المثال التالي كيفية السماح للمستخدم بزيادة مستوى التكبير لعلامة تبويب تم التقاطها مباشرةً من تطبيق الالتقاط:

const zoomIncreaseButton = document.getElementById('zoomInButton');
zoomIncreaseButton.addEventListener('click', async (event) => {
  if (controller.zoomLevel >= controller.getSupportedZoomLevels().at(-1)) {
    return;
  }
  try {
    await controller.increaseZoomLevel();
  } catch (error) {
    // Inspect the error.
    // ...
  }
});

يوضّح المثال التالي كيفية الاستجابة لتغييرات مستوى التكبير/التصغير في علامة تبويب تم التقاطها:

controller.addEventListener('zoomlevelchange', (event) => {
  const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
  zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});

رصد الميزات

للتحقّق مما إذا كانت واجهات برمجة التطبيقات Captured Surface Control متوافقة، استخدِم ما يلي:

if (!!window.CaptureController?.prototype.forwardWheel) {
  // CaptureController forwardWheel() is supported.
}

يمكنك أيضًا استخدام أي من واجهات Captured Surface Control API الأخرى، مثل increaseZoomLevel أو decreaseZoomLevel، أو التحقّق من جميعها.

دعم المتصفح

تتوفّر ميزة "التحكّم في السطح الذي تم التقاطه" من الإصدار 136 من Chrome على أجهزة الكمبيوتر المكتبي فقط.

الأمان والخصوصية

تتيح لك "captured-surface-control" سياسة الأذونات إدارة طريقة وصول تطبيق التسجيل وإطارات iframe المضمّنة التابعة لجهات خارجية إلى "عناصر التحكّم في السطح الذي تم تسجيله". للتعرّف على المفاضلات بين الأمان والخصوصية، يمكنك الاطّلاع على قسم اعتبارات الخصوصية والأمان في شرح "عنصر التحكّم في السطح الذي تم التقاطه".

عرض توضيحي

يمكنك تجربة Captured Surface Control من خلال تشغيل العرض التوضيحي.

الملاحظات

يريد فريق Chrome ومنتدى معايير الويب معرفة تجاربك مع Captured Surface Control.

أخبِرنا عن التصميم

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

هل تواجه مشكلة في التنفيذ؟

هل عثرت على خطأ في تنفيذ Chrome؟ أو هل يختلف التنفيذ عن المواصفات؟ يمكنك الإبلاغ عن الخطأ على https://new.crbug.com. احرص على تضمين أكبر قدر ممكن من التفاصيل، بالإضافة إلى تعليمات حول كيفية إعادة إنتاج الخطأ.