ApsaraVideo VOD：情境類型

概念介紹

什麼是 SceneType？

SceneType 是告知播放器當前運行在什麼業務情境中的枚舉標識。設定 SceneType 後，AliPlayerKit 會自動：

• 調整插槽可見度（如直播情境隱藏封面圖）。

• 過濾手勢行為（如直播/受限情境禁用進度拖拽和倍速，視頻列表情境禁用垂直手勢）。

• 適配功能限制（如受限情境確保使用者按序完整觀看）。

開發人員只需設定一個枚舉值，架構自動完成上述適配，極大降低不同業務情境的定製成本。

核心價值

功能特性

情境概覽

AliPlayerKit 內建 5 種情境類型，覆蓋絕大多數播放業務：

枚舉定義

// SceneType.h
typedef NS_ENUM(NSInteger, SceneType) {
    /** ApsaraVideo for VOD情境（預設） */
    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:videoUrl];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeVideoList;

[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];