场景类型

概念介绍

什么是 SceneType？

SceneType 是告知播放器当前运行在什么业务场景中的枚举标识。设置 SceneType 后，AliPlayerKit 会自动：

• 调整插槽可见性（如直播场景隐藏封面图）。

• 过滤手势行为（如直播/受限场景禁用进度拖拽和倍速，视频列表场景禁用垂直手势）。

• 适配功能限制（如受限场景确保用户按序完整观看）。

开发者只需设置一个枚举值，框架自动完成上述适配，极大降低不同业务场景的定制成本。

核心价值

功能特性

场景概览

AliPlayerKit 内置 5 种场景类型，覆盖绝大多数播放业务：

枚举定义

// SceneType.h
typedef NS_ENUM(NSInteger, SceneType) {
    /** 视频点播场景（默认） */
    SceneTypeVOD = 0,

    /** 直播场景 */
    SceneTypeLive = 1,

    /** 视频列表或短视频流场景 */
    SceneTypeVideoList = 2,

    /** 受限播放场景 */
    SceneTypeRestricted = 3,

    /** 极简播放页场景 */
    SceneTypeMinimal = 4,
};

场景能力矩阵

插槽可见性

插槽系统根据场景类型自动控制组件可见性。以下矩阵反映 DefaultSlotFactory.defaultConfigs 的默认规则：

可见性规则说明：

• PlayerSurface 和 PlayState：所有场景可见（无 excludedScenes 配置）。

• Cover：在 Live、Restricted、Minimal 场景中不可见。

• 其余插槽（GestureControl、LandscapeHint、CenterDisplay、LogPanel、TopBar、BottomBar、SettingMenu、OptionPanel）：仅在 Minimal场景中不可见。

手势行为差异

GestureControlSlot 内部根据 currentSceneType 在各手势处理方法中进行场景过滤：

过滤逻辑说明：

• Minimal：所有手势的处理方法入口处直接 return（handleSingleTap: / handleDoubleTap: / handleLongPress: / handlePan:）。

• Live / Restricted：长按和水平拖动被过滤（handleLongPress: 和 tryStartDragWithCurrentPoint: 中检查）。

• VideoList：垂直拖动被过滤（tryStartDragWithCurrentPoint: 中检查 SceneTypeVideoList 时直接 return）。

使用方式

基本用法

场景类型通过 AliPlayerModel.sceneType 属性指定。默认为 SceneTypeVOD，无需显式设置。

点播场景（默认，无需设置）：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
// model.sceneType 默认为 SceneTypeVOD，无需设置

[controller configure:model];

直播场景：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://live.example.com/stream.m3u8"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeLive;
model.videoTitle = @"直播间";

[controller configure:model];

视频列表场景：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://live.example.com/stream.m3u8"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeLive;
model.videoTitle = @"直播间";

[controller configure:model];

各场景详细说明

VOD - 点播场景（默认）

适用场景：常规视频播放、在线课程、媒体库浏览等。

能力说明：

• 支持全部 11 种默认插槽

• 支持全部 6 种手势

• 支持进度拖拽、倍速播放、清晰度切换

• 支持全屏切换

// 无需显式指定 SceneType，默认即为 VOD
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.coverUrl = @"https://example.com/cover.jpg";
model.videoTitle = @"精彩视频";
model.autoPlay = YES;

[controller configure:model];

Live - 直播场景

适用场景：实时直播、赛事直播、电商直播等。

与 VOD 的关键差异：

• 禁用：进度拖拽（水平手势）、倍速播放（长按手势）（因为直播无固定时长）

• 隐藏：封面图插槽（直播流无需封面）

• 保留：单击/双击手势、音量/亮度调节

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:liveSource];
model.sceneType = SceneTypeLive;
model.videoTitle = @"热门直播";
model.autoPlay = YES;

[controller configure:model];

VideoList - 视频列表场景

适用场景：信息流中的内嵌视频、短视频列表、可滑动视频集合等。

与 VOD 的关键差异：

• 禁用：左侧/右侧垂直拖动手势（避免与列表 UIScrollView 滑动冲突）

• 保留：其余所有功能（进度拖拽、倍速、单击/双击/长按等）

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeVideoList;
model.autoPlay = YES;

[controller configure:model];

Restricted - 受限播放场景

适用场景：在线考试监控视频、培训认证课程、版权保护场景等。

与 VOD 的关键差异：

• 禁用：进度拖拽（水平手势）、倍速播放（长按手势）（确保用户按序完整观看）

• 隐藏：封面图插槽

• 保留：单击/双击手势、音量/亮度调节

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeRestricted;
model.videoTitle = @"安全培训课程";
model.autoPlay = YES;
// 通常配合禁止截屏
model.disableScreenshot = YES;

[controller configure:model];

Minimal - 极简模式

适用场景：背景播放、完全自定义 UI、预览缩略图播放等。

与 VOD 的关键差异：

• 隐藏：几乎所有 UI 控制插槽（仅保留 PlayerSurface 和 PlayState）

• 禁用：所有手势（GestureControl 插槽在 Minimal 场景不可见，且内部手势处理方法均会直接 return）

• 适用：需要完全自定义播放控制 UI 的场景

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

[controller configure:model];
// 所有控制需要自行通过 controller 的 API 实现
// 例如：[controller play]; [controller pause]; [controller seekTo:position];

自定义开发

插槽可见性微调

当场景预设的插槽可见性不完全满足需求时，可通过 SlotConfig 进行微调：

// 示例：在 Live 场景下额外隐藏 TopBar
SlotConfig *topBarConfig = [SlotConfig configWithSlotType:SlotTypeTopBar
                                           excludedScenes:[NSSet setWithObjects:
                                               @(SceneTypeMinimal),
                                               @(SceneTypeLive), nil]];

// 注册到 SlotManager（覆盖该插槽类型的默认 SlotConfig）
[playerView.slotManager registerSlotConfig:topBarConfig];

也可以通过 hideSlot: 直接隐藏整个插槽，不依赖场景判断：

// 无条件隐藏 TopBar（需调用 rebuildSlots 生效）
[playerView.slotManager hideSlot:SlotTypeTopBar];

手势行为微调

手势控制支持两种微调方式：

方式一：通过 SlotManager 的元素位掩码 API 禁用特定手势（推荐，在 attach 前配置即可）：

// 在 VOD 场景下禁用长按倍速
[playerView.slotManager hideElements:GestureElementLongPress
                             forSlot:SlotTypeGestureControl];

方式二：通过 GestureControlSlotConfig 直接控制（需在 attach 后获取插槽实例）：

// 获取手势控制插槽实例
GestureControlSlot *gestureSlot = (GestureControlSlot *)[playerView.slotManager slotViewForType:SlotTypeGestureControl];

// 修改配置（立即生效）
GestureControlSlotConfig *config = [GestureControlSlotConfig defaultConfig];
config.longPressEnabled = NO;
config.horizontalDragEnabled = NO;
gestureSlot.config = config;

在Minimal场景下注册自定义插槽

在 Minimal 场景下，大多数默认插槽被场景配置排除。如需恢复某个插槽，可覆盖其 SlotConfig：

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

// 覆盖 BottomBar 的场景配置，移除 Minimal 排除规则
[playerView.slotManager registerSlotConfig:
    [SlotConfig configWithSlotType:SlotTypeBottomBar]]; // 无 excludedScenes = 所有场景可见

[controller configure:model];

动态可见性条件

使用 SlotConfig 的 visibilityCondition 回调实现运行时动态控制：

SlotConfig *coverConfig = [SlotConfig configWithSlotType:SlotTypeCover
                                          excludedScenes:nil
                                     visibilityCondition:^BOOL{
    // 仅在有封面 URL 时显示封面插槽
    return model.coverUrl != nil;
}];

[playerView.slotManager registerSlotConfig:coverConfig];

场景选择指南

决策流程

需要播放器控制 UI 吗？
├── 否 → SceneTypeMinimal
└── 是 → 是直播流吗？
         ├── 是 → SceneTypeLive
         └── 否 → 播放器嵌入可滚动列表中吗？
                   ├── 是 → SceneTypeVideoList
                   └── 否 → 需要防止用户跳播吗？
                             ├── 是 → SceneTypeRestricted
                             └── 否 → SceneTypeVOD（默认）

场景选择汇总表

API 速查

SceneType枚举

SlotConfig

GestureControlSlotConfig

SlotManager场景相关API

相关文件

完整API详见API参考。

最佳实践

注意事项

常见问题

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;
[controller configure:model];

// 通过 controller API 直接控制
[controller play];
[controller pause];
[controller seekTo:30000]; // 跳到 30 秒

// 恢复水平拖动手势（进度跳转）
[playerView.slotManager showElements:GestureElementHorizontalDrag
                             forSlot:SlotTypeGestureControl];