تتيح لك واجهات برمجة التطبيقات android.media.projection التي تم تقديمها في Android 5 (مستوى واجهة برمجة التطبيقات 21) تسجيل محتوى شاشة الجهاز كبث وسائط يمكنك تشغيله أو تسجيله أو بثه على أجهزة أخرى، مثل أجهزة التلفزيون.
يقدّم Android 14 (المستوى 34 لواجهة برمجة التطبيقات) ميزة مشاركة شاشة التطبيق، والتي تتيح للمستخدمين مشاركة نافذة تطبيق واحدة بدلاً من شاشة الجهاز بأكملها بغض النظر عن وضع النوافذ. تستبعد ميزة مشاركة شاشة التطبيق شريط الحالة وشريط التنقّل والإشعارات وعناصر واجهة المستخدم الأخرى في النظام من العرض المشترَك، حتى عند استخدام ميزة مشاركة شاشة التطبيق لتسجيل تطبيق في وضع ملء الشاشة. تتم مشاركة محتوى التطبيق المحدّد فقط.
تضمن ميزة "مشاركة شاشة التطبيق" خصوصية المستخدم وتزيد من إنتاجيته وتحسّن من تعدد المهام من خلال السماح للمستخدمين بتشغيل تطبيقات متعددة مع حصر مشاركة المحتوى على تطبيق واحد فقط.
ثلاثة تمثيلات للعرض
تلتقط ميزة "عرض الوسائط" محتوى شاشة الجهاز أو نافذة التطبيق، ثم تعرض الصورة الملتقَطة على شاشة افتراضية تعرض الصورة على Surface.
Surface الذي يوفّره التطبيق.
يوفّر التطبيق Surface من خلال MediaRecorder أو SurfaceTexture أو ImageReader، ما يستهلك محتوى الشاشة التي تم التقاطها ويتيح لك إدارة الصور المعروضة على Surface في الوقت الفعلي. يمكنك حفظ الصور كتسجيل أو بثّها على تلفزيون أو جهاز آخر.
شاشة عرض حقيقية
ابدأ جلسة بث محتوى الشاشة من خلال الحصول على رمز مميّز يمنح تطبيقك
القدرة على تسجيل محتوى شاشة الجهاز أو نافذة التطبيق. يتم تمثيل الرمز المميّز
بمثيل من فئة MediaProjection.
استخدِم طريقة getMediaProjection() لخدمة نظام MediaProjectionManager لإنشاء مثيل MediaProjection عند بدء نشاط جديد. ابدأ النشاط باستخدام نية من طريقة
createScreenCaptureIntent() لتحديد عملية التقاط الشاشة:
val mediaProjectionManager = getSystemService(MediaProjectionManager::class.java) var mediaProjection: MediaProjection? val startMediaProjection = registerForActivityResult( StartActivityForResult() ) { result -> if (result.resultCode == RESULT_OK) { result.data?.let { data -> mediaProjection = mediaProjectionManager .getMediaProjection(result.resultCode, data) } } } startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent())
الشاشة الافتراضية
العنصر الأساسي في عرض الوسائط هو العرض الافتراضي الذي تنشئه من خلال استدعاء createVirtualDisplay() في مثيل MediaProjection:
virtualDisplay = mediaProjection.createVirtualDisplay( "ScreenCapture", width, height, screenDensity, DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, surface, null, null )
تحدّد المَعلمتان width وheight أبعاد العرض الافتراضي. للحصول على قيم العرض والارتفاع، استخدِم واجهات برمجة التطبيقات WindowMetrics التي تم تقديمها في Android 11 (المستوى 30 لواجهة برمجة التطبيقات). (لمعرفة التفاصيل، يُرجى الاطّلاع على قسم حجم عرض الوسائط).
سطح
يجب تحديد حجم سطح عرض الوسائط لإنتاج مخرجات بالدقة المناسبة. اجعل السطح كبيرًا (دقة منخفضة) لبث الشاشة على أجهزة التلفزيون أو شاشات الكمبيوتر وصغيرًا (دقة عالية) لتسجيل شاشة الجهاز.
اعتبارًا من الإصدار Android 12L (مستوى واجهة برمجة التطبيقات 32)، عند عرض المحتوى الذي تم التقاطه على السطح، يغيّر النظام حجم المحتوى بشكل موحّد، مع الحفاظ على نسبة العرض إلى الارتفاع، بحيث يكون كلا بُعدَي المحتوى (العرض والارتفاع) مساويًا أو أقل من الأبعاد المقابلة للسطح. يتم بعد ذلك توسيط المحتوى الذي تم التقاطه على السطح.
يعمل نهج تغيير الحجم في Android 12L على تحسين بث الشاشة على أجهزة التلفزيون والشاشات الكبيرة الأخرى من خلال زيادة حجم صورة السطح إلى أقصى حد مع ضمان نسبة العرض إلى الارتفاع المناسبة.
إذن الوصول إلى الخدمة التي تعمل في المقدّمة
إذا كان تطبيقك يستهدف الإصدار 14 من نظام التشغيل Android أو الإصدارات الأحدث، يجب أن يتضمّن بيان التطبيق
بيان إذن لنوع الخدمة التي تعمل في المقدّمة mediaProjection:
<manifest ...>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
<application ...>
<service
android:name=".MyMediaProjectionService"
android:foregroundServiceType="mediaProjection"
android:exported="false">
</service>
</application>
</manifest>
ابدأ خدمة عرض الوسائط من خلال طلب startForeground().
إذا لم تحدّد نوع الخدمة التي تعمل في المقدّمة في الطلب، يتم ضبط النوع تلقائيًا على عدد صحيح ثنائي من أنواع الخدمات التي تعمل في المقدّمة والمحدّدة في ملف البيان. إذا لم يحدّد البيان أي أنواع خدمات، يعرض النظام الخطأ MissingForegroundServiceTypeException.
موافقة المستخدمين
يجب أن يطلب تطبيقك موافقة المستخدم قبل كل جلسة لعرض الوسائط. الجلسة هي طلب واحد إلى createVirtualDisplay(). يجب استخدام رمز MediaProjection المميّز
مرة واحدة فقط لإجراء المكالمة.
في الإصدار 14 من نظام التشغيل Android أو الإصدارات الأحدث، تُظهر الطريقة createVirtualDisplay() الخطأ
SecurityException إذا كان تطبيقك ينفّذ أيًا مما يلي:
- يتم تمرير مثيل
Intentتم إرجاعه منcreateScreenCaptureIntent()إلىgetMediaProjection()أكثر من مرة - يتم استدعاء
createVirtualDisplay()أكثر من مرة في مثيلMediaProjectionنفسه
حجم عرض الوسائط
يمكن أن تلتقط ميزة "بث محتوى الشاشة" شاشة الجهاز بأكملها أو نافذة تطبيق بغض النظر عن وضع النوافذ.
الحجم الأوّلي
عند عرض الوسائط بملء الشاشة، يجب أن يحدّد تطبيقك حجم شاشة الجهاز. عند مشاركة شاشة التطبيق، لن يتمكّن تطبيقك من تحديد حجم الشاشة التي يتم تسجيلها إلى أن يختار المستخدم منطقة التسجيل. وبالتالي، يكون الحجم الأولي لأي بث وسائط هو حجم شاشة الجهاز.
استخدِم طريقة WindowManager getMaximumWindowMetrics() في النظام الأساسي لعرض عنصر WindowMetrics لشاشة الجهاز حتى إذا كان التطبيق المضيف لبث الوسائط في وضع النوافذ المتعددة ويشغل جزءًا فقط من الشاشة.
للتوافق مع مستوى واجهة برمجة التطبيقات 14، استخدِم طريقة WindowMetricsCalculator
computeMaximumWindowMetrics() من مكتبة WindowManager
في Jetpack.
استدعِ طريقة WindowMetrics getBounds() للحصول على عرض وارتفاع شاشة الجهاز.
تغييرات في الحجم
يمكن أن يتغيّر حجم عرض الوسائط عند تدوير الجهاز أو عندما يختار المستخدم نافذة تطبيق كمنطقة تسجيل في ميزة مشاركة شاشة التطبيق. قد يتم عرض المحتوى المسجَّل على الشاشة مع أشرطة سوداء إذا كان حجمه مختلفًا عن الحد الأقصى لمقاييس النافذة التي تم الحصول عليها عند إعداد ميزة تسجيل الشاشة.
لضمان توافق عرض الوسائط بدقة مع حجم المحتوى الذي تم تسجيله لأي منطقة تم تسجيلها وعبر عمليات تدوير الجهاز، استخدِم دالة الاستدعاء onCapturedContentResize() لتغيير حجم التسجيل. (لمزيد من المعلومات، يُرجى الاطّلاع على قسم التخصيص أدناه).
التخصيص
يمكن لتطبيقك تخصيص تجربة المستخدم في ميزة "عرض الوسائط" باستخدام واجهات برمجة التطبيقات التالية في MediaProjection.Callback:
onCapturedContentVisibilityChanged(): يتيح هذا الإذن للتطبيق المضيف (التطبيق الذي بدأ بث الوسائط) إظهار المحتوى المشترَك أو إخفاءه.يمكنك استخدام هذه الدالة لتخصيص واجهة مستخدم تطبيقك استنادًا إلى ما إذا كانت المنطقة التي تم تسجيلها مرئية للمستخدم. على سبيل المثال، إذا كان تطبيقك مرئيًا للمستخدم ويعرض المحتوى الذي تم تسجيله ضمن واجهة مستخدم التطبيق، وكان التطبيق الذي تم تسجيله مرئيًا أيضًا للمستخدم (كما هو موضّح من خلال هذا الاستدعاء)، يرى المستخدم المحتوى نفسه مرتين. استخدِم دالة الاستدعاء لتعديل واجهة مستخدم تطبيقك لإخفاء المحتوى الذي تم تسجيله وإخلاء مساحة في تنسيق تطبيقك لمحتوى آخر.
onCapturedContentResize(): تتيح هذه الميزة للتطبيق المضيف تغيير حجم بث الوسائط على الشاشة الافتراضية وبث الوسائطSurfaceاستنادًا إلى حجم منطقة العرض التي يتم تسجيلها.يتم تشغيله عندما يتغيّر حجم المحتوى الذي يتم تسجيله، سواء كان نافذة تطبيق واحدة أو شاشة الجهاز بالكامل (بسبب تدوير الجهاز أو دخول التطبيق الذي يتم تسجيله في وضع نافذة مختلف). استخدِم واجهة برمجة التطبيقات هذه لتغيير حجم كل من العرض الافتراضي والسطح لضمان تطابق نسبة العرض إلى الارتفاع مع المحتوى الذي تم تسجيله وعدم اقتصاص التسجيل.
استرداد الموارد
يجب أن يسجّل تطبيقك دالة الاستدعاء MediaProjection onStop() ليتم إعلامك عند إيقاف جلسة عرض الوسائط وتصبح غير صالحة. عند إيقاف الجلسة، يجب أن يحرّر تطبيقك الموارد التي يحتفظ بها، مثل العرض الافتراضي وسطح العرض. لا يمكن لجلسة عرض الوسائط التي تم إيقافها إنشاء شاشة افتراضية جديدة، حتى إذا لم يسبق لتطبيقك إنشاء شاشة افتراضية لعرض الوسائط هذا.
يستدعي النظام دالة الاستدعاء عند إنهاء عرض الوسائط. ويمكن أن يحدث هذا الإنهاء لعدة أسباب، مثل:
- يوقف المستخدم الجلسة باستخدام واجهة مستخدم التطبيق أو شريحة شريط حالة عرض الوسائط في النظام
- يتم قفل الشاشة
- بدء جلسة أخرى لبث الوسائط
- يتم إيقاف عملية التطبيق
إذا لم يسجّل تطبيقك دالة الاستدعاء، فسيؤدي أي طلب إلى createVirtualDisplay() إلى ظهور الخطأ IllegalStateException.
إيقاف
يوفّر نظام التشغيل Android 14 أو الإصدارات الأحدث ميزة مشاركة شاشة التطبيق تلقائيًا. تتيح كل جلسة عرض وسائط للمستخدمين خيار مشاركة نافذة تطبيق أو الشاشة بأكملها.
يمكن لتطبيقك إيقاف ميزة مشاركة شاشة التطبيق من خلال استدعاء طريقة createScreenCaptureIntent(MediaProjectionConfig) باستخدام وسيطة MediaProjectionConfig يتم عرضها من استدعاء createConfigForDefaultDisplay().
إنّ استدعاء createScreenCaptureIntent(MediaProjectionConfig) باستخدام وسيطة MediaProjectionConfig يتم عرضها من استدعاء createConfigForUserChoice() هو نفسه الإعداد التلقائي، أي استدعاء createScreenCaptureIntent().
تطبيقات يمكن تغيير حجمها
احرص دائمًا على إتاحة تغيير حجم تطبيقات بث محتوى الشاشة
(resizeableActivity="true"). تتيح التطبيقات التي يمكن تغيير حجمها إجراء تغييرات في إعدادات الجهاز
واستخدام وضع النوافذ المتعددة (يُرجى الاطّلاع على إتاحة وضع النوافذ المتعددة).
إذا كان تطبيقك غير قابل لتغيير الحجم، يجب أن يطلب حدود العرض من سياق النافذة ويستخدم getMaximumWindowMetrics() لاسترداد WindowMetrics الحد الأقصى لمساحة العرض المتاحة للتطبيق :
val windowContext = context.createWindowContext( context.display, WindowManager.LayoutParams.TYPE_APPLICATION, null ) val projectionMetrics = windowContext.getSystemService(WindowManager::class.java) .maximumWindowMetrics
شريحة شريط الحالة والإيقاف التلقائي
تؤدي إساءة استخدام ميزة "إلقاء الشاشة" إلى تعريض بيانات المستخدمين الخاصة، مثل معلوماتهم المالية، لأنّ المستخدمين لا يدركون أنّه تتم مشاركة شاشة أجهزتهم.
بالنسبة إلى التطبيقات التي تعمل على الأجهزة التي تعمل بنظام التشغيل Android 15 QPR1 أو إصدار أحدث، يتم عرض شريحة ملف شخصي كبيرة ومميّزة في شريط الحالة لتنبيه المستخدمين بأي عملية بث شاشة جارية. يمكن للمستخدمين النقر على الشريحة لإيقاف مشاركة الشاشة أو بثها أو تسجيلها. ويتوقف أيضًا عرض الشاشة تلقائيًا عند قفل شاشة الجهاز.
اختبِر توفُّر شريحة حالة عرض الوسائط في شريط الحالة من خلال بدء مشاركة الشاشة أو بثّها أو تسجيلها. من المفترض أن تظهر الشريحة في شريط الحالة.
لضمان أن يحرّر تطبيقك الموارد ويعدّل واجهة المستخدم عند إيقاف بث الشاشة من خلال تفاعل المستخدم مع شريحة شريط الحالة أو من خلال تفعيل شاشة القفل، اتّبِع الخطوات التالية:
أنشئ مثيلاً من
MediaProjection.Callback.نفِّذ طريقة ردّ الاتصال
onStop(). يتم استدعاء هذه الطريقة عند إيقاف عرض الشاشة. يجب تحرير أي موارد يحتفظ بها تطبيقك وتحديث واجهة مستخدم التطبيق حسب الحاجة.
لاختبار ردّ الاتصال، انقر على شريحة شريط الحالة أو اقفل شاشة الجهاز لإيقاف
عرض الشاشة. تأكَّد من استدعاء طريقة onStop() وأنّ تطبيقك
يستجيب على النحو المطلوب.
مراجع إضافية
لمزيد من المعلومات حول عرض الوسائط، يُرجى الاطّلاع على مقالة تسجيل تشغيل الفيديو والصوت.