UI theme - ApsaraVideo VOD - Alibaba Cloud Documentation Center

AliPlayerWidget provides a unified UI design specification, including icon asset management and style tokens. The UI theme system lets you quickly replace the player skin for brand customization.

Default UI design

AliPlayerWidget includes a complete, built-in UI design that works out-of-the-box:

AliPlayerWidget(controller)

The default design includes:

Icon asset: Unified icon filename constants (PlayerIcons).
Style specification: Unified style tokens for color, font size, size, and spacing (PlayerStyles).

Custom skin

To replace the entire set of icon assets, pass the assetsPath parameter.

Step 1: Create an asset directory

Create an asset folder in your application's root directory:

your_app/
└── assets/
    └── player_icons/      # Custom directory name
        ├── ic_back.svg
        ├── ic_settings.svg
        └── ...

Step 2: Register the assets

flutter:
  assets:
    - assets/player_icons/

Step 3: Pass the path

Pass the custom path when initializing the widget:

AliPlayerWidget(
  controller,
  assetsPath: 'assets/player_icons',
)

Icon asset specification

Format selection

Format	Use cases	Description
SVG (Recommended)	Solid-color or monochrome vector icons	A single file supports all resolutions, eliminating the need for multi-resolution asset slicing.
PNG	Icons with gradients or multiple colors	Requires 1x, 2x, and 3x resolution variants.

Naming convention

ic_<description>[_<status>].svg

Prefix: The ic_ prefix indicates an icon asset.
Naming: Use snake_case to avoid cross-platform issues.
Status suffix: Use suffixes such as _on/_off, _done, and _exit. Do not use numbers to indicate states.

Example:

Filename	Description
`ic_back.svg`	Back button
`ic_settings.svg`	Settings button
`ic_play.svg`	Play button
`ic_pause.svg`	Pause button
`ic_download.svg`	Download button (not downloaded)
`ic_download_done.svg`	Download complete

PNG multi-resolution specification

If you use the PNG format, you must provide assets for three resolutions in the following directory structure:

assets/player_icons/
├── ic_back.png          # 1x (baseline)
├── 2.0x/
│   └── ic_back.png      # 2x
└── 3.0x/
    └── ic_back.png      # 3x

Note

Place the 1x file in the root directory, not in a 1.0x/ subdirectory. Flutter automatically recognizes the 2.0x/ and 3.0x/ directories as resolution variants.

Advanced UI control

The slot system provides fine-grained UI control, allowing you to hide specific buttons or replace entire control bars.

The slot system allows you to:

Customize any UI module, such as the top bar, bottom bar, or settings panel.
Hide individual elements within a slot.
Completely replace a slot's component.

For details, see slot system.

API reference

Parameters

Parameter	Type	Default	Description
`assetsPath`	`String`	Path to assets within the package	Path to the icon asset directory

Usage example

import 'package:aliplayer_widget/theme/player_theme.dart';

// Icon
SvgPicture.asset(
  PlayerAssetsScope.iconPath(context, PlayerIcons.back),
  width: PlayerStyles.iconSizeTopBar,
)

// Text
Text(
  'Title',
  style: TextStyle(
    fontSize: PlayerStyles.fontSizeTitle,
    color: PlayerStyles.colorOnPrimary,
  ),
)

Notes

SVG files should only contain a viewBox attribute. Do not hardcode width and height, as the code controls the rendering size.
When creating a custom skin, your icon filenames must match the default ones.
After registering the directory, you can add new icons without modifying the pubspec.yaml file.