إدارة المحتوى وتشغيله

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

تتناول هذه الصفحة المواضيع التالية:

إضافة ملفات وسائط إلى مدير التحميل المُسبَق

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

لإجراء ذلك، استخدِم طريقة إضافة مجمّعة مثل addMediaItems. يمكنك بدلاً من ذلك استدعاء add (أو addMediaSource) لإضافة ملفات الوسائط بشكل فردي. ومع ذلك، فإن إضافة ملفات وسائط بشكل فردي لا تؤدي إلى تشغيل التحميل المسبق تلقائيًا. عند استخدام الطرق الفردية، يجب استدعاء invalidate بشكل صريح بعد الانتهاء من إضافة العناصر لإعلام مدير التحميل المُسبَق بتعديل الأولويات وبدء التحميل المُسبَق.

val initialMediaItems = pullMediaItemsFromService(count = 20)
val rankingDataList = initialMediaItems.indices.toList()
preloadManager.addMediaItems(initialMediaItems, rankingDataList)

نقاط رئيسية حول الرمز

  • يعرض هذا المقتطف كيفية تعبئة مدير التحميل المُسبق في وضع الدفعة بعد إنشائه. يمكنك استدعاء addMediaItems لإضافة عناصر إلى مدير تحميل مُسبَق حالي وممتلئ.
  • في هذا المقتطف، يمثّل pullMediaItemsFromService() منطق التطبيق لجلب قائمة المحتوى المطلوب تشغيله. يستدعي الرمز هذه الطريقة لجلب قائمة تضم ما يصل إلى 20 عنصرًا.
  • ‫preloadManager هي DefaultPreloadManager التي تم إنشاؤها في مقالة إنشاء DefaultPreloadManager.
  • ‫rankingData هي قيمة يستخدمها مدير التحميل المُسبَق لتحديد أولوية كل ملف وسائط. بالنسبة إلى DefaultPreloadManager، يمثّل rankingData عددًا صحيحًا يشير إلى موضع العنصر في لوحة العرض الدوّارة. يحدّد مدير التحميل المُسبق الأولوية حسب بُعد كل عنصر عن العنصر الذي يتم تشغيله حاليًا.

جلب الوسائط وتشغيلها

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

عليك أيضًا تعديل فهرس التشغيل الحالي في مدير التحميل المُسبَق من خلال استدعاء setCurrentPlayingIndex، ما يتيح لمدير التحميل المُسبَق تحديد أولويات عمليات التحميل المُسبَق المستقبلية.

// When a media item is about to be displayed on the screen
val mediaSource = preloadManager.getMediaSource(mediaItem)
if (mediaSource != null) {
  player.setMediaSource(mediaSource)
} else {
  // If the mediaSource is null, its mediaItem hasn't been added to the preload
  // manager yet. Send it directly to the player when it's about to play.
  player.setMediaItem(mediaItem)
}
player.prepare()

// When the media item is being displayed at the center of the screen ("in focus")
player.play()
// Update the current playing index to let the preload manager know where the user
// is in the carousel/pagination/list.
preloadManager.setCurrentPlayingIndex(currentIndex)

نقاط رئيسية حول الرمز

  • ‫player هو ExoPlayer في Media3 الذي يستخدمه التطبيق لتشغيل المحتوى. يجب إنشاء هذا المشغّل من خلال استدعاء DefaultPreloadManager.Builder.buildExoPlayer() في أداة الإنشاء نفسها التي استخدمتها لإنشاء مدير التحميل المُسبَق.
  • عندما ينتقل المستخدم إلى ملف وسائط جديد، يستدعي التطبيق getMediaSource() للحصول على مصدر الوسائط من مدير التحميل المُسبَق. يجب أن يكون هذا mediaItem سبق لك إضافته إلى مدير التحميل المُسبَق. لا بأس إذا لم يبدأ مدير التحميل المُسبَق في تحميل المحتوى، ففي هذه الحالة، يتم عرض MediaSource لا يتضمّن بيانات تم تحميلها مُسبَقًا. على سبيل المثال، قد يحدث ذلك إذا انتقل المستخدم فجأة إلى مكان بعيد في لوحة العرض الدوّارة.
  • بعد أن يشغّل المستخدم ملف الوسائط الجديد، يمكنك استدعاء setCurrentPlayingIndex لإعلام مدير التحميل المُسبَق بمكان الملف الجديد في لوحة العرض الدوّارة. يحتاج مدير التحميل المُسبَق إلى هذه المعلومات لتحديد أولوية تحميل الملف التالي.

إزالة العناصر من "مدير التحميل المُسبَق"

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

إذا كانت لديك قائمة بملفات الوسائط التي تريد إزالتها، يمكنك استخدام removeMediaItems. يمكنك بدلاً من ذلك استدعاء remove (أو removeMediaSource) لإزالة ملفات الوسائط بشكل فردي.

preloadManager.removeMediaItems(mediaItemsToRemove)

نقاط رئيسية حول الرمز

  • إذا أردت إزالة جميع العناصر من مدير التحميل المُسبَق، يمكنك استدعاء reset() بدلاً من remove(). هذا الأسلوب مفيد إذا كنت بحاجة إلى تغيير جميع العناصر في لوحة العرض الدوّارة. في هذه الحالة، بعد إزالة العناصر، عليك إضافة عناصر جديدة إلى مدير التحميل المُسبَق.

إلغاء تفعيل مدير التحميل المُسبَق عند الانتهاء من استخدامه

عندما لا تعود بحاجة إلى مدير التحميل المُسبَق، عليك إيقافه لإخلاء موارده. على وجه الخصوص، يجب التأكّد من إيقاف الجلسة عند إيقاف نشاطك.

preloadManager.release()

نقاط رئيسية حول الرمز

  • يجب عدم استدعاء أي من إجراءات العنصر بعد إيقافه.
  • إذا كنت بحاجة إلى إنشاء مدير تحميل مسبق آخر، أنشِئ DefaultPreloadManager.Builder جديدًا واستخدِمه لإنشاء DefaultPreloadManager. لا تحاول إعادة استخدام أداة الإنشاء القديمة.