إضافة عناصر التحكّم في التشغيل إلى تطبيقك

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

Kotlin

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

Groovy

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

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

PlayerView يتضمن طريقة setPlayer للإرفاق والفصل (من خلال اجتياز 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 يوفر العديد من ذات الصلة. يمكن استخدام هذه السمات لتخصيص سلوك طريقة العرض، مثل بالإضافة إلى شكله وأسلوبه. تحتوي معظم هذه السمات على دالة setter مقابلة والتي يمكن استخدامها لتخصيص طريقة العرض في وقت التشغيل. تشير رسالة الأشكال البيانية PlayerView يسرد Javadoc هذه السمات وطرق الإعداد في بمزيد من التفصيل.

بعد تعريف العرض في ملف التنسيق، يمكن البحث عنه في طريقة واحدة (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();

اختيار نوع السطح

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

إذا كانت المشاهدة لتشغيل الفيديو العادي، يتم استخدام surface_view أو texture_view. تنبؤي. توفِّر حزمة "SurfaceView" عددًا من المزايا تفوق "TextureView" لنطاق تشغيل الفيديو:

  • طاقة أقل بشكل كبير على العديد الأجهزة.
  • توفير توقيت عرض إطارات أكثر دقة، ما يؤدي إلى تشغيل الفيديو بشكل أكثر سلاسة
  • يتيح هذا الخيار استخدام إخراج فيديو HDR بجودة أعلى على الأجهزة المتوافقة.
  • إتاحة إخراج آمن عند تشغيل محتوى محمي بموجب إدارة الحقوق الرقمية
  • إمكانية عرض محتوى الفيديو بدقة الشاشة الكاملة على أجهزة Android TV التي تعمل على تحسين طبقة واجهة المستخدم

لذلك، يجب تفضيل SurfaceView على TextureView حيثما أمكن. يجب استخدام TextureView فقط في حال عدم تلبية SurfaceView لاحتياجاتك. وَاحِدْ على سبيل المثال، يجب الحصول على صور متحركة سلسة أو التمرير على سطح الفيديو قبل الإصدار Android 7.0 (المستوى 24 لواجهة برمجة التطبيقات)، كما هو موضّح في الملاحظات التالية. بالنسبة هذه الحالة، من المفضّل استخدام TextureView فقط عندما تكون قيمة SDK_INT أقل 24 (Android 7.0) وSurfaceView بخلاف ذلك.

التنقّل باستخدام لوحة التحكّم على Android TV

يتضمّن جهاز التحكّم عن بُعد في Android TV لوحة تحكّم في لوحة التحكّم ترسل الأوامر وصلت كحدث رئيسي في dispatchKeyEvent(KeyEvent) من Activity. هذه تفويضك إلى عرض المشغّل:

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

إنّ طلب التركيز في عرض المشغّل مهم أثناء التشغيل. عناصر التحكم وتخطي الإعلانات. يمكنك طلب التركيز في onCreate من Activity:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

إذا كنت تستخدم ميزة Compose على Android TV، عليك إنشاء AndroidView. يمكن التركيز عليه وتفويض الحدث من خلال تمرير معلَمة التعديل إلى AndroidView وفقًا لذلك:

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

تجاهُل العناصر القابلة للرسم

يستخدم PlayerView PlayerControlView لعرض التشغيل. عناصر التحكم وشريط التقدم. يمكن للعناصر القابلة للرسم التي يستخدمها "PlayerControlView" أن يتم تجاوزها بالعناصر القابلة للرسم التي تحمل الأسماء نفسها المحددة في تطبيقك. عرض Javadoc PlayerControlView للحصول على قائمة بعناصر التحكّم القابلة للرسم التي يمكن تجاوزه.

المزيد من التخصيص

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