ApsaraVideo VOD:Slot system

Slot types

The system provides the following slot types, listed in stacking order from bottom to top:

Usage

Default UI

The player uses the built-in default UI by default, requiring no configuration:

AliPlayerWidget(controller)

Customize slots

Use the slotBuilders parameter to customize any slot. Unspecified slots use the default UI.

Partial customization

Replace only the slots you need to customize and keep the rest as default:

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

Full customization

Customize all slots to build a fully tailored UI:

AliPlayerWidget(
  controller,
  slotBuilders: {
    // Note: Customizing playerSurface is not recommended.
    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(),
  },
)

SlotWidgetBuilder type

The slot system currently uses a concise builder signature:

// Current signature (recommended)
typedef SlotWidgetBuilder = Widget Function(BuildContext context);

// Legacy signature (deprecated)
@Deprecated('Please use SlotWidgetBuilder instead')
typedef SlotWidgetBuilderWithController = Widget Function(
  BuildContext context,
  AliPlayerWidgetController controller,
);

Hide slots

Set a slot's builder to null to hide that slot:

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

Fine-grained control

To hide specific elements (such as buttons) in a default slot without replacing the entire slot, use hiddenSlotElements:

AliPlayerWidget(
  controller,
  hiddenSlotElements: const {
    // Hide the Download and Snapshot buttons in the top bar
    SlotType.topBar: {
      TopBarElements.download,
      TopBarElements.snapshot,
    },
    // Disable double-tap and vertical swipe gestures in playback control
    SlotType.playControl: {
      PlayControlElements.doubleTap,
      PlayControlElements.leftVerticalDrag,
      PlayControlElements.rightVerticalDrag,
    },
  },
)

Custom UI and layer control

Unlike traditional overlay-only solutions, the slot system lets you insert custom UI components at any layer in the player, not just the top one. Use defaultOrder to control the rendering order with precision. This lets you place components such as watermarks, bullet screens, and ads at the exact layer you need:

SlotType is an extensible class. You can create custom slot types and control their layer position using defaultOrder:

// Create a custom slot type and set its layer order between coverImage (30) and playControl (40).
const myWatermark = SlotType('watermark', defaultOrder: 35);

AliPlayerWidget(
  controller,
  slotBuilders: {
    myWatermark: (context) => MyWatermarkWidget(),
  },
  // All slots are automatically sorted by defaultOrder; no manual enumeration is required.
)

How it works

The slot system uses a three-level rendering strategy:

1. Custom first: The system uses any custom builder provided for a slot.

2. Default fallback: The system uses its default builder if no custom one is provided.

3. Explicitly hidden: The system hides a slot if its builder is null.

Scene adaptation

The behavior of certain slots automatically adapts based on the playback scene (SceneType):

• vod (VOD scene): All slot functions are supported.

• live (live scene): Slot functions for progress bar dragging are disabled.

• listPlayer (list player scene): Slot functions for vertical gestures are disabled.

• restricted (restricted playback scene): Slot functions for timeline operations are disabled.

• minimal (minimal playback scene): Only the playerSurface slot appears.

Example

For a complete example of using the slot system, see example/lib/pages/slot/slot_demo_page.dart.

The slot system makes it easy to create a player UI for a wide range of use cases.