بدء استخدام واجهة المستخدِم المستندة إلى "العروض"

إضافة التبعية

Kotlin

implementation("androidx.media3:media3-ui:1.7.1")

Groovy

implementation "androidx.media3:media3-ui:1.7.1"

PlayerView

المكوّن الأكثر أهمية هو PlayerView، وهو طريقة عرض لتشغيل الوسائط. يعرض PlayerView الفيديو والصور والترجمة والشاشة الرئيسية للألبوم أثناء التشغيل، بالإضافة إلى عناصر التحكّم في التشغيل.

تتضمّن PlayerView طريقة setPlayer() لربط مثيلات Player وفصلها (من خلال تمرير null).

يمكن استخدام PlayerView لتشغيل الفيديوهات والصور والمحتوى الصوتي. يعرض هذا التطبيق الفيديو والترجمة والشرح في حال تشغيل الفيديو، كما يعرض الصور النقطية عند تشغيل الصور، ويمكنه عرض الأعمال الفنية المضمّنة كبيانات وصفية في الملفات الصوتية. يمكنك تضمينها في ملفات التصميم مثل أي مكوّن آخر من مكونات واجهة المستخدم. على سبيل المثال، يمكن تضمين PlayerView باستخدام XML التالي:

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

توضّح المقتطفات أعلاه أنّ PlayerView يوفّر العديد من السمات. يمكن استخدام هذه السمات لتخصيص سلوك العرض، بالإضافة إلى مظهره. معظم هذه السمات لها طرق ضبط مقابلة، ويمكن استخدامها لتخصيص العرض في وقت التشغيل. تتضمّن مستندات PlayerView قائمة بهذه السمات وطُرق الضبط بتفصيل أكبر.

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

android:keepScreenOn="true"

بعد تعريف طريقة العرض في ملف التنسيق، يمكن البحث عنها في طريقة onCreate الخاصة بالنشاط:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

بعد تهيئة المشغّل، يمكن ربطه بالعرض من خلال استدعاء setPlayer:

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

PlayerControlView

PlayerControlView هي إحدى طرق العرض الفرعية PlayerView التي تحتوي على شريط التقدم وأزرار التحكّم في التشغيل. يُرجى العِلم أنّ PlayerControlView ليس مخصّصًا للاستخدام كمكوّن مستقل خارج PlayerView. يمكن تخصيصها من خلال ضبط السمات على PlayerView (التي سيتم تمريرها إلى PlayerControlView) أو توفير أداة تحكّم مخصّصة باستخدام android:id="@id/exo_controller.

اختيار نوع مساحة العرض

تتيح لك السمة surface_type الخاصة بالعنصر PlayerView ضبط نوع مساحة العرض المستخدَمة لتشغيل الفيديو. القيم المسموح بها هي surface_view وtexture_view وspherical_gl_surface_view (وهي قيمة خاصة لتشغيل الفيديو الكروي) وvideo_decoder_gl_surface_view (وهي مخصّصة لعرض الفيديو باستخدام أدوات العرض الإضافية) وnone (وهي مخصّصة لتشغيل الصوت فقط). يمكنك العثور على مزيد من المعلومات حول نوع المساحة الذي يجب اختياره في صفحة "المساحة".