باستخدام واجهة برمجة التطبيقات لميزة "التقاط الشاشة"، يمكنك التقاط صورة لعلامة التبويب الحالية بالكامل. تتيح لك Element Capture API التقاط عنصر HTML محدّد وتسجيله. وهو يحوِّل التقاط علامة التبويب بالكامل إلى التقاط لشجرة فرعية معيّنة في نموذج العناصر في المستند (DOM)، مع التقاط الأيائل المباشرة فقط للعنصر المستهدَف. بمعنى آخر، تعمل هذه الميزة على اقتصاص المحتوى وإخفائه وتزيله.
مزايا استخدام ميزة Element Capture
يمكن أن يساعدك التفكير في متطلبات تطبيق اجتماعات الفيديو في فهم الجوانب التي تكون فيها ميزة "التقاط العناصر" مفيدة. إذا كان لديك تطبيق لعقد اجتماعات الفيديو يتيح لك تضمين تطبيقات من جهات خارجية في إطار iframe، فقد تحتاج أحيانًا إلى التقاط صورة لإطار iframe هذا كفيديو ونقله إلى المشاركين عن بُعد.
![لقطة شاشة لمكالمة في مؤتمر فيديو في Chrome.](https://developer.chrome.com/static/docs/web-platform/element-capture/image/1.png?authuser=6&hl=ar)
سيؤدي الاتصال بالرقم getDisplayMedia()
والسماح للمستخدم باختيار علامة التبويب الحالية إلى نقل علامة التبويب الحالية بالكامل. من المحتمل أن يؤدي ذلك إلى إعادة إرسال الفيديو الخاص بالأشخاص إليهم. يمكنك اقتصاص هذه المنطقة باستخدام ميزة التقاط المنطقة.
ومع ذلك، ماذا لو تفاعل مقدم العرض مع تطبيق مؤتمرات الفيديو وكان بعض المحتوى، مثل القائمة المنسدلة، يتصادف أن يظهر فوق المحتوى المقصود للالتقاط؟
![لقطة شاشة لقائمة منسدلة تغطي المحتوى المخصّص للتصوير](https://developer.chrome.com/static/docs/web-platform/element-capture/image/2.png?authuser=6&hl=ar)
ولا يمكنك الاستفادة هنا من ميزة تسجيل المناطق. قد يظهر جزء من القائمة المنسدلة على شاشات المشاركين عن بُعد.
![تم التقاط لقطة شاشة لقائمة منسدلة.](https://developer.chrome.com/static/docs/web-platform/element-capture/image/3.png?authuser=6&hl=ar)
وتؤدي حقيقة أنّ ميزة "تسجيل المناطق" تلتقط أجزاءً من العناصر بهذه الطريقة (المعروفة باسم إخفاء المحتوى) إلى حدوث مشاكل متعدّدة:
- قد يؤدي إخفاء المحتوى إلى حجب المحتوى الذي قصد المستخدم مشاركته.
- قد يكون إخفاء محتوى المحتوى خاصًا (يمكنك التفكير في إشعارات المحادثات).
- قد يكون إخفاء المحتوى مربكًا. (على سبيل المثال، يمكن أن تؤدي إعادة تصميم التطبيق إلى عرض مقاطع الفيديو الخاصة بالمشاركين عن بُعد فوق الهدف الذي تم الحصول عليه لفترة وجيزة.)
تحل Element Capture API كل هذه المشاكل من خلال السماح لك باستهداف العنصر الذي تريد مشاركته.
![لقطة شاشة للعنصر المستهدَف بدون قائمة منسدلة](https://developer.chrome.com/static/docs/web-platform/element-capture/image/4.png?authuser=6&hl=ar)
كيف يمكنني استخدام ميزة Element Capture؟
captureTarget
هو عنصر على صفحتك يتضمن المحتوى الذي يرغب المستخدم في الحصول عليه. تريد من تطبيق الويب لاجتماعات الفيديو التقاط صورة "captureTarget
" ومشاركتها مع المشاركين عن بُعد. إذًا، يمكنك اشتقاق RestrictionTarget
من captureTarget
. بعد حصر إمكانية الوصول إلى مقطع الفيديو باستخدام RestrictionTarget
هذا، أصبحت اللقطات في مقطع الفيديو هذا تتألف الآن فقط من وحدات البكسل التي تشكل جزءًا من captureTarget
وعناصر DOM المباشرة الخاصة به.
إذا غيّرت captureTarget
الحجم أو الشكل أو الموقع الجغرافي، تتم متابعة المقطع الصوتي ضمن الفيديو بدون الحاجة إلى أي إدخال إضافي من أيّ من تطبيقَي الويب. إنّ إخفاء محتوى يظهر أو اختفائه أو تغيير مكانه لا يتطلّب أي معاملة خاصة.
راجع هذه الخطوات مرة أخرى:
ابدأ بالسماح للمستخدم بالتقاط علامة التبويب الحالية.
// Ask the user for permission to start capturing the current tab.
const stream = await navigator.mediaDevices.getDisplayMedia({
preferCurrentTab: true,
});
const [track] = stream.getVideoTracks();
يمكنك تحديد RestrictionTarget
من خلال استدعاء RestrictionTarget.fromElement()
مع إدراج عنصر من اختيارك كإدخال.
// Associate captureTarget with a new RestrictionTarget
const captureTarget = document.querySelector("#captureTarget");
const restrictionTarget = await RestrictionTarget.fromElement(captureTarget);
بعد ذلك، عليك الاتصال بالرقم restrictTo()
على مسار الفيديو وضبط RestrictionTarget
كإدخال. وبعد انتهاء الوعد الأخير، سيتم فرض قيود على جميع اللقطات اللاحقة.
// Start restricting the self-capture video track using the RestrictionTarget.
await track.restrictTo(restrictionTarget);
// Enjoy! Transmit remotely.
نظرة تفصيلية
رصد الميزات
لمعرفة ما إذا كانت "RestrictionTarget.fromElement()
" متاحة، استخدِم:
if ("RestrictionTarget" in self && "fromElement" in RestrictionTarget) {
// Deriving a restriction target is supported.
}
استنتاج هدف تقييد
يجب التركيز على العنصر المُسمّى captureTarget
. لاستخراج RestrictionTarget
منها، يمكنك الاتصال بالرقم RestrictionTarget.fromElement(captureTarget)
. سيتم التعامل مع الوعد الذي تم إرجاعه باستخدام عنصر RestrictionTarget
جديد في حال نجاحه. في حال عدم استيفاء هذا الشرط، سيتم رفضه إذا استخدَمت عددًا غير معقول من العناصر في RestrictionTarget
.
const captureTarget = document.querySelector("#captureTarget");
const restrictionTarget = await RestrictionTarget.fromElement(captureTarget);
على عكس العنصر، الكائن RestrictionTarget
يمكن تسلسله. على سبيل المثال، يمكن تمريرها إلى مستند آخر باستخدام Window.postMessage()
.
تقييد
عند التقاط علامة تبويب، يعرض مقطع الفيديو restrictTo()
. عند التقاط علامة التبويب الحالية، يمكن استدعاء الدالة restrictTo()
إما مع null
أو أي RestrictionTarget
مشتق من عنصر داخل علامة التبويب الحالية.
تعمل المكالمات إلى restrictTo(restrictionTarget)
على تحويل مسار الفيديو إلى التقاط لـ captureTarget
، كما لو كان قد تم رسمه بمفرده، بشكل مستقل عن بقية DOM. يتم أيضًا التقاط أي عناصر تابعة لـ captureTarget
، ويتم استبعاد الأشقاء من captureTarget
من الالتقاط. والنتيجة هي أنّ أي إطارات يتم عرضها على المقطع الصوتي تظهر كما لو تم اقتصاصها وفق مخطط الخطوط العريضة لـ captureTarget
، كما تتم إزالة أي محتوى مغطى وغير مغطى.
// Start restricting the self-capture video track using the RestrictionTarget.
await track.restrictTo(restrictionTarget);
تؤدي الطلبات التي يتم إجراؤها إلى restrictTo(null)
إلى إعادة مسار المقطع الصوتي إلى حالته الأصلية.
// Stop restricting.
await track.restrictTo(null);
إذا تم الاتصال برقم restrictTo()
بنجاح، يتم حلّ الوعد الذي تم إرجاعه عندما يمكن ضمان أنّ جميع إطارات الفيديو اللاحقة ستقتصر على captureTarget
.
وفي حال عدم نجاح العملية، سيتم رفض الوعد. يرجع عدم نجاح الاتصال برقم restrictTo()
إلى أحد الأسباب التالية:
- ما إذا تم صياغة
restrictionTarget
في علامة تبويب غير علامة التبويب التي يتم تسجيلها. (لاحظ أنه باستخدام الزر "مشاركة علامة التبويب هذه بدلاً من ذلك"، يمكن للمستخدمين تغيير علامة التبويب التي يتم التقاطها في أي وقت.) - تشير هذه السمة إلى ما إذا كانت السمة
restrictionTarget
مشتقة من عنصر لم يعُد متوفّرًا. - إذا كان المقطع الصوتي يتضمّن نُسخًا طبق الأصل (راجِع المشكلة 1509418.)
- إذا لم يكن المقطع الصوتي الحالي مقطع فيديو بالتقاط ذاتي
- إذا كان العنصر الذي تم اشتقاق
restrictionTarget
منه غير مؤهل للحظر.
اعتبارات التقاط الذات
عندما يتصل تطبيقٌ ما بـ getDisplayMedia()
، ويختار المستخدم تسجيل علامة التبويب الخاصة بالتطبيق، نُطلق على هذه العملية اسم "الالتقاط الذاتي".
يتم عرض الطريقة restrictTo()
في أي مسار فيديو يتم تسجيله باستخدام علامة تبويب، وليس فقط في الالتقاط الذاتي. غير أنّ ميزة Element Capture غير مفعّلة حاليًا لالتقاط صورة ذاتية. ولذلك من المستحسن التحقق مما إذا كان المستخدم قد اختار علامة التبويب الحالية قبل محاولة تقييد المسار. ويمكن تحقيق ذلك باستخدام مقبض الالتقاط. يمكن أيضًا أن تطلب من المتصفّح توجيه المستخدم نحو الالتقاط الذاتي باستخدام preferCurrentTab
.
الشفافية
إنّ إطارات الفيديو التي يتخطّاها التطبيق getDisplayMedia()
لا تتضمّن قناة ألفا. في حال ضبط التطبيق على هدف التقاط شفاف جزئيًا، قد ينتج عن إزالة قناة ألفا بعض النتائج المحتملة:
- قد تتغير الألوان. قد تظهر العناصر المستهدفة الشفافة جزئيًا المرسومة على خلفية فاتحة بلون أغمق عند إزالة قناة ألفا، بينما قد تظهر العناصر المستهدفة المرسومة على خلفية داكنة بلون أفتح.
- الألوان التي كانت غير مرئية أو غير مرئية للمستخدم عند ضبط قناة ألفا على الحد الأقصى، ستظهر بعد إزالة قناة ألفا. على سبيل المثال، قد يؤدي ذلك إلى ظهور مناطق سوداء غير متوقّعة في اللقطات التي تم التقاطها، إذا كانت الأقسام الشفافة تحتوي على رمز RGBA
rgba(0, 0, 0, 0)
.
![لقطة شاشة لهدف التقاط شفاف غير مستطيل.](https://developer.chrome.com/static/docs/web-platform/element-capture/image/transparency.png?authuser=6&hl=ar)
أهداف جذب غير مؤهَّلة
من الممكن دائمًا البدء بحصر المسار على أي هدف جذب صالح. ومع ذلك، لن يتم إنشاء اللقطات في ظل شروط معيّنة، مثلاً إذا كان العنصر أو الأصل display:none
. يتمثّل الأساس المنطقي العام في أنّ التقييد لا ينطبق إلّا على عنصر يضمّ منطقة مستطيلة واحدة متماسكة وثنائية الأبعاد يمكن تحديد وحدات بكسلها منطقيًا بمعزل عن أي عناصر رئيسية أو تابعة.
من الاعتبارات المهمة للتأكُّد من أهلية العنصر للقيود أنّه يجب أن يُشكِّل سياق التكديس الخاص به. للتأكّد من ذلك، يمكنك تحديد خاصية CSS للعزل وضبطها على isolate
.
<div id="captureTarget" style="isolation: isolate;"></iframe>
يُرجى العِلم أنّه يمكن للعنصر المستهدف التبديل بين أن يكون مؤهَّلاً وغير مؤهَّل للحظر في أي مرحلة عشوائية، على سبيل المثال في حال غيّر التطبيق خصائص CSS الخاصة به. يعود الأمر إلى التطبيق في استخدام أهداف الالتقاط المعقولة وتجنب تغيير خصائصها بشكل غير متوقع. وإذا أصبح العنصر المستهدف غير مؤهل، لن يتم نشر الإطارات الجديدة على المسار إلى أن يصبح العنصر المستهدف مؤهلاً للتقييد مرة أخرى.
تفعيل التقاط العناصر
تتوفّر واجهة Element Capture API في متصفّح Chrome على أجهزة الكمبيوتر المكتبي خلف علامة Element Capture ويمكن تفعيلها على chrome://flags/#element-capture
.
تدخل هذه الميزة أيضًا في مرحلة التجربة والتقييم من Chrome 121 على أجهزة الكمبيوتر المكتبي، ما يسمح للمطوّرين بتفعيل الميزة لزوّار مواقعهم الإلكترونية من أجل جمع البيانات من مستخدمين حقيقيين. يُرجى الاطّلاع على بدء استخدام مراحل التجربة والتقييم للحصول على مزيد من المعلومات عن مراحل التجربة والتقييم.
الأمان والخصوصية
لفهم الإيجابيات والسلبيات المتعلّقة بالأمان، يمكنك الاطّلاع على قسم اعتبارات الخصوصية والأمان في مواصفات "التقاط العناصر".
يرسم متصفّح Chrome حدًا أزرق حول حواف علامات التبويب التي تم التقاطها.
عرض توضيحي
يمكنك اللعب باستخدام ميزة Element Capture من خلال تشغيل العرض التوضيحي على Glitch. تأكّد من الاطّلاع على رمز المصدر.
ملاحظات
يرغب فريق Chrome ومنتدى معايير الويب في التعرّف على تجاربك في استخدام ميزة Element Capture.
أخبِرنا عن التصميم
هل هناك شيء ما في ميزة تسجيل المناطق لا يعمل كما توقعت؟ أو هل هناك طرق أو خصائص مفقودة تحتاجها لتنفيذ فكرتك؟ هل لديك سؤال أو تعليق بشأن نموذج الأمان؟
- يُرجى الإبلاغ عن مشكلة في المواصفات في مستودع GitHub، أو إضافة أفكارك إلى مشكلة حالية.
هل تواجه مشكلة في عملية التنفيذ؟
هل واجهت مشكلة في التنفيذ في Chrome؟ أم أن التنفيذ يختلف عن المواصفات؟
- يُرجى الإبلاغ عن الخطأ على https://new.crbug.com. واحرص على تضمين أكبر قدر ممكن من التفاصيل، بالإضافة إلى تعليمات بسيطة لإعادة إنتاج الخطأ. تعمل ميزة الخطأ بشكلٍ رائع لمشاركة النسخ المُعاد إنتاجها بسرعة وسهولة.
روابط مفيدة
خدمات الإقرار
تصوير بول سكوروبسكا على موقع Unسباش