يمكن حاليًا مشاركة علامات التبويب والنوافذ والشاشات على منصة الويب باستخدام Screen Capture API. عندما يطلب تطبيق ويب getDisplayMedia()، يطلب Chrome من المستخدم مشاركة علامة تبويب أو نافذة أو شاشة مع تطبيق الويب كفيديو MediaStreamTrack.
تعرض العديد من تطبيقات الويب التي تستخدم getDisplayMedia() للمستخدم معاينة فيديو للسطح الذي تم التقاطه. على سبيل المثال، غالبًا ما تبث تطبيقات مؤتمرات الفيديو هذا الفيديو للمستخدمين البعيدين، كما تعرضه على HTMLVideoElement على الجهاز، حتى يتمكن المستخدم المحلي من الاطّلاع باستمرار على معاينة لما يشاركونه.
تقدّم هذه المستندات واجهة برمجة التطبيقات الجديدة Captured Surface Control API في Chrome، والتي تتيح لتطبيق الويب الانتقال إلى علامة تبويب تم التقاطها، بالإضافة إلى قراءة مستوى التكبير/التصغير لعلامة التبويب التي تم التقاطها وكتابته.
لماذا يجب استخدام عنصر التحكّم في المساحة التي تمّ التقاطها؟
تواجه جميع تطبيقات مؤتمرات الفيديو المشكلة نفسها. إذا أراد المستخدم التفاعل مع علامة تبويب أو نافذة تم التقاطها، عليه التبديل إلى تلك المساحة، ما ينقل المستخدم بعيدًا عن تطبيق مكالمات الفيديو. ويؤدي ذلك إلى بعض التحديات:
- لا يمكن للمستخدم رؤية التطبيق الذي تم تسجيله وخلاصات الفيديو الخاصة بالمستخدمين البعيدين في الوقت نفسه ما لم يستخدم ميزة نافذة ضمن النافذة أو نافذتَين منفصلتَين جنبًا إلى جنب لعلامة التبويب الخاصة باجتماع الفيديو وعلامة التبويب المشترَكة. قد يكون ذلك صعبًا على شاشة أصغر حجمًا.
- يضطر المستخدم إلى التبديل بين تطبيق مكالمات الفيديو ومساحة العرض التي تم التقاطها.
- يفقد المستخدم إمكانية الوصول إلى عناصر التحكّم التي يعرضها تطبيق مكالمات الفيديو عندما لا يكون متصلاً به، مثل تطبيق محادثة مضمّن وتفاعلات الرموز التعبيرية والإشعارات بشأن المستخدمين الذين يطلبون الانضمام إلى المكالمة وعناصر التحكّم في الوسائط المتعددة والتنسيقات وغيرها من الميزات المفيدة لمكالمات الفيديو.
- لا يمكن للمقدّم تفويض التحكّم للمشاركين عن بُعد. يؤدّي ذلك إلى السيناريو المعتاد الذي يطلب فيه المستخدمون عن بُعد من المُقدّم تغيير الشريحة أو الانتقال للأعلى أو للأسفل قليلاً أو ضبط مستوى التكبير/التصغير.
تعالج واجهة برمجة التطبيقات 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}%`;
});
رصد الميزات
للتحقّق مما إذا كانت واجهات برمجة التطبيقات الخاصة بعناصر التحكّم في السطح الذي تم التقاطه متاحة، استخدِم:
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
من الممكن أيضًا استخدام أيّ من مساحات عرض واجهة برمجة التطبيقات Captured Surface Control API الأخرى، مثل increaseZoomLevel أو decreaseZoomLevel، أو التحقّق من جميعها.
دعم المتصفح
تتوفّر ميزة "التحكّم في المساحة التي تم التقاطها" من الإصدار 136 من Chrome على أجهزة الكمبيوتر المكتبي فقط.
الأمان والخصوصية
تتيح لك سياسة الأذونات في "captured-surface-control" إدارة كيفية وصول تطبيق الالتقاط وإطارات iframe التابعة لجهات خارجية المضمّنة إلى عنصر التحكّم في المساحة التي تم التقاطها. لفهم المفاضلات الأمنية، اطّلِع على قسم الاعتبارات المتعلّقة بالخصوصية والأمان في الشرح التفصيلي عن ميزة "التحكّم في السطح الذي تم التقاطه".
عرض توضيحي
يمكنك تجربة ميزة "عناصر التحكّم في السطح الذي تمّ التقاطه" من خلال تشغيل الإصدار التجريبي على Glitch. احرص على الاطّلاع على رمز المصدر.
الملاحظات
يريد فريق Chrome ومجتمع معايير الويب معرفة تجاربك مع عنصر التحكّم في المساحة التي تمّ التقاطها.
أخبِرنا عن التصميم
هل هناك مشكلة في ميزة "التقاط السطح المُسجَّل" لا تعمل على النحو المتوقّع؟ هل هناك طرق أو سمات غير متوفّرة تحتاجها لتنفيذ فكرتك؟ هل لديك سؤال أو تعليق حول نموذج الأمان؟ يمكنك الإبلاغ عن مشكلة في المواصفات على مستودع GitHub، أو إضافة أفكارك إلى مشكلة حالية.
هل هناك مشكلة في التنفيذ؟
هل رصدت خطأ في عملية تنفيذ Chrome؟ أم أنّ عملية التنفيذ مختلفة عن المواصفات؟ يمكنك الإبلاغ عن خطأ على الرابط https://new.crbug.com. احرص على تضمين أكبر قدر ممكن من التفاصيل، بالإضافة إلى تعليمات لإعادة إنتاج الخطأ. يُعدّ تطبيق Glitch مثاليًا لمشاركة الأخطاء التي يمكن تكرارها.