ApsaraVideo VOD:Sistem Slot

Jenis slot

Sistem menyediakan jenis-jenis slot berikut, yang disusun berdasarkan urutan penumpukan dari bawah ke atas:

Penggunaan

UI default

Pemutar secara otomatis menggunakan UI default bawaan tanpa memerlukan konfigurasi tambahan:

AliPlayerWidget(controller)

Kustomisasi slot

Gunakan parameter slotBuilders untuk mengkustomisasi slot mana pun. Slot yang tidak ditentukan akan menggunakan UI default.

Kustomisasi parsial

Ganti hanya slot yang perlu dikustomisasi dan biarkan sisanya menggunakan UI default:

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: (context) => MyCustomTopBar(),
  },
)

Kustomisasi penuh

Kustomisasi semua slot untuk membangun UI yang sepenuhnya disesuaikan:

AliPlayerWidget(
  controller,
  slotBuilders: {
    // Catatan: Mengkustomisasi playerSurface tidak disarankan.
    SlotType.topBar: (context) => MyCustomTopBar(),
    SlotType.bottomBar: (context) => MyCustomBottomBar(),
    SlotType.playControl: (context) => MyPlayControl(),
    SlotType.coverImage: (context) => MyCoverImage(),
    SlotType.playState: (context) => MyPlayState(),
    SlotType.centerDisplay: (context) => MyCenterDisplay(),
    SlotType.seekThumbnail: (context) => MySeekThumbnail(),
    SlotType.subtitle: (context) => MySubtitle(),
    SlotType.settingMenu: (context) => MySettingMenu(),
    SlotType.overlays: (context) => MyOverlays(),
  },
)

Tipe SlotWidgetBuilder

Sistem slot saat ini menggunakan tanda tangan builder yang ringkas:

// Tanda tangan saat ini (disarankan)
typedef SlotWidgetBuilder = Widget Function(BuildContext context);

// Tanda tangan lama (tidak digunakan lagi)
@Deprecated('Please use SlotWidgetBuilder instead')
typedef SlotWidgetBuilderWithController = Widget Function(
  BuildContext context,
  AliPlayerWidgetController controller,
);

Sembunyikan slot

Atur builder suatu slot ke null untuk menyembunyikan slot tersebut:

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: null,
    SlotType.bottomBar: null,
  },
)

Kontrol tingkat detail

Untuk menyembunyikan elemen tertentu (seperti tombol) dalam slot default tanpa mengganti seluruh slot, gunakan hiddenSlotElements:

AliPlayerWidget(
  controller,
  hiddenSlotElements: const {
    // Sembunyikan tombol Download dan Snapshot di top bar
    SlotType.topBar: {
      TopBarElements.download,
      TopBarElements.snapshot,
    },
    // Nonaktifkan gestur double-tap dan swipe vertikal di playback control
    SlotType.playControl: {
      PlayControlElements.doubleTap,
      PlayControlElements.leftVerticalDrag,
      PlayControlElements.rightVerticalDrag,
    },
  },
)

UI kustom dan kontrol lapisan

Berbeda dengan solusi overlay tradisional, sistem slot memungkinkan Anda menyisipkan komponen UI kustom pada lapisan apa pun dalam pemutar, bukan hanya lapisan paling atas. Gunakan defaultOrder untuk mengontrol urutan rendering secara presisi. Hal ini memungkinkan penempatan komponen seperti watermark, bullet screen, dan iklan pada lapisan yang tepat sesuai kebutuhan:

SlotType adalah kelas yang dapat diperluas. Anda dapat membuat jenis slot kustom dan mengontrol posisi lapisannya menggunakan defaultOrder:

// Buat jenis slot kustom dan atur urutan lapisannya di antara coverImage (30) dan playControl (40).
const myWatermark = SlotType('watermark', defaultOrder: 35);

AliPlayerWidget(
  controller,
  slotBuilders: {
    myWatermark: (context) => MyWatermarkWidget(),
  },
  // Semua slot secara otomatis diurutkan berdasarkan defaultOrder; tidak perlu enumerasi manual.
)

Cara kerja

Sistem slot menggunakan strategi rendering tiga tingkat:

1. Kustom terlebih dahulu: Sistem menggunakan builder kustom yang disediakan untuk suatu slot.

2. Fallback default: Sistem menggunakan builder default jika tidak ada builder kustom yang disediakan.

3. Secara eksplisit disembunyikan: Sistem menyembunyikan slot jika buildernya bernilai null.

Adaptasi skenario

Perilaku slot tertentu secara otomatis menyesuaikan diri berdasarkan skenario pemutaran (SceneType):

• vod (skenario VOD): Semua fungsi slot didukung.

• live (skenario siaran langsung): Fungsi slot untuk menarik bilah kemajuan dinonaktifkan.

• listPlayer (skenario pemutar daftar): Fungsi slot untuk gestur vertikal dinonaktifkan.

• restricted (skenario pemutaran terbatas): Fungsi slot untuk operasi garis waktu (timeline) dinonaktifkan.

• minimal (skenario pemutaran minimal): Hanya slot playerSurface yang ditampilkan.

Contoh

Untuk contoh lengkap penggunaan sistem slot, lihat example/lib/pages/slot/slot_demo_page.dart.

Sistem slot memudahkan pembuatan UI pemutar untuk berbagai kasus penggunaan.