插槽系统

什么是插槽系统？

插槽系统 (Slot System) 是统一管理插槽的架构机制，负责插槽的注册、生命周期、场景适配、渲染顺序及运行时状态控制。基于该机制，开发者可灵活使用默认插槽快速搭建 UI，或按需替换、扩展乃至完全自定义组件，实现高度定制化的播放器界面。

什么是插槽？

插槽 (Slot) 是播放器 UI 的基本组成单元，代表独立的界面组件（如顶部控制栏、底部进度条、封面图等）。所有插槽按预定义 Z-Order 叠加构成完整界面，各自仅关注自身的展示与交互逻辑，实现职责清晰、粒度可控的结构。

核心价值

插槽系统将播放器UI组件独立拆解，开发者可自主选择使用方式。

架构优势：

• 解耦：UI组件与播放器核心逻辑分离，职责清晰。

• 灵活：运行时动态组合、替换UI组件。

• 可扩展：无需修改框架即可自定义UI，扩展性强。

• 关注点分离：UI样式（XML布局）与业务逻辑（Slot类处理）分离。

场景适配

AliPlayerKit 定义了 5 种播放场景，不同场景下插槽的可见性和行为自动适配。场景适配通过 SlotConfig 实现，DefaultSlotFactory 预置了所有内置插槽的默认配置。

插槽可见性规则（由 DefaultSlotFactory.defaultConfigs 定义）：

手势行为差异：

策略一：使用默认界面

最简单的使用方式，零配置开箱即用：

@implementation PlayerViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // 1. 创建播放器视图
    AliPlayerView *playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
    [self.view addSubview:playerView];

    // 2. 创建控制器
    AliPlayerController *controller = [[AliPlayerController alloc] init];

    // 3. 创建数据模型
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:videoSource];
    model.sceneType = SceneTypeVOD;
    model.autoPlay = YES;

    // 4. 配置并绑定（自动使用默认插槽）
    [controller configure:model];
    [playerView attach:controller];
}

@end

策略二：自定义部分插槽

只替换需要定制的插槽，其他使用默认实现：

// 1. 获取播放器视图的 SlotManager
SlotManager *slotManager = playerView.slotManager;

// 2. 只注册需要自定义的插槽（其他保持默认）
[slotManager registerSlotType:SlotTypeTopBar provider:^UIView<SlotProtocol> *(UIView *parentView) {
    return [[MyCustomTopBarSlot alloc] initWithFrame:parentView.bounds];
}];

// 3. 配置并绑定
[controller configure:model];
[playerView attach:controller];

策略三：完全自定义界面

清除所有默认配置，逐一注册自定义插槽：

// 1. 获取 SlotManager 并清除默认配置
SlotManager *slotManager = playerView.slotManager;
[slotManager clearAll];

// 2. 注册所有需要的自定义插槽
[slotManager registerSlotType:SlotTypePlayerSurface provider:^UIView<SlotProtocol> *(UIView *parentView) {
    return [[MySurfaceSlot alloc] initWithFrame:parentView.bounds];
}];
[slotManager registerSlotType:SlotTypeCover provider:^UIView<SlotProtocol> *(UIView *parentView) {
    return [[MyCoverSlot alloc] initWithFrame:parentView.bounds];
}];
// ... 其他插槽

// 3. 绑定
[controller configure:model];
[playerView attach:controller];

插槽可见性控制

不替换插槽实现，仅控制显示/隐藏：

SlotManager *slotManager = playerView.slotManager;

// 隐藏整个插槽（rebuildSlots 时不构建）
[slotManager hideSlot:SlotTypeLogPanel];

// 显示之前隐藏的插槽（需调用 rebuildSlots 生效）
[slotManager showSlot:SlotTypeLogPanel];
[slotManager rebuildSlots];

// 检查插槽是否被隐藏
BOOL hidden = [slotManager isSlotHidden:SlotTypeLogPanel];

元素级可见性控制

插槽系统支持对插槽内部的单个 UI 元素进行细粒度可见性控制，通过位掩码（SlotElements.h）实现：

SlotManager *slotManager = playerView.slotManager;

// 隐藏顶部栏中的下载按钮和截图按钮
[slotManager hideElements:(TopBarElementDownload | TopBarElementSnapshot)
                  forSlot:SlotTypeTopBar];

// 隐藏底部栏中的刷新按钮
[slotManager hideElements:BottomBarElementRefresh
                  forSlot:SlotTypeBottomBar];

// 禁用水平拖动手势（对 GestureControl 插槽，隐藏元素表示禁用对应手势）
[slotManager hideElements:GestureElementHorizontalDrag
                  forSlot:SlotTypeGestureControl];

// 显示之前隐藏的元素
[slotManager showElements:TopBarElementDownload
                  forSlot:SlotTypeTopBar];

// 批量设置所有插槽的隐藏元素（替换式）
[slotManager setAllHiddenElementMasks:@{
    @(SlotTypeTopBar): @(TopBarElementDownload | TopBarElementSnapshot),
    @(SlotTypeBottomBar): @(BottomBarElementRefresh),
}];

// 清空所有元素可见性配置
[slotManager clearAllElementMasks];

元素位掩码类型：

场景可见性配置

通过 SlotConfig 控制插槽在不同场景下的可见性：

SlotManager *slotManager = playerView.slotManager;

// 配置封面图插槽在 Live 和 Restricted 场景下不可见
SlotConfig *coverConfig = [SlotConfig configWithSlotType:SlotTypeCover
                                         excludedScenes:[NSSet setWithObjects:@(SceneTypeLive), @(SceneTypeRestricted), nil]];
[slotManager registerSlotConfig:coverConfig];

// 使用 visibilityCondition 进行动态可见性控制
SlotConfig *logConfig = [SlotConfig configWithSlotType:SlotTypeLogPanel
                                       excludedScenes:[NSSet setWithObject:@(SceneTypeMinimal)]
                                  visibilityCondition:^BOOL{
    return [AliPlayerKit isDebugModeEnabled];
}];
[slotManager registerSlotConfig:logConfig];

// 移除场景可见性配置（该插槽在所有场景下均可见）
[slotManager unregisterSlotConfigForType:SlotTypeCover];

// 查询配置
SlotConfig *config = [slotManager slotConfigForType:SlotTypeCover];
BOOL visible = [config isVisibleInScene:SceneTypeLive];

插槽协议（SlotProtocol）

所有插槽必须遵循 SlotProtocol，该协议定义了插槽的最小生命周期契约：

@protocol SlotProtocol <NSObject>

#pragma mark - View 生命周期

/// 插槽被附加到宿主时调用
- (void)onAttach:(id<SlotHost>)host;

/// 插槽从宿主分离时调用
- (void)onDetach;

#pragma mark - Data 生命周期

/// 数据绑定回调
- (void)onBindData:(AliPlayerModel *)model;

/// 数据解绑回调
- (void)onUnbindData;

@end

SlotProvider 是构建插槽视图的 Block 类型：

typedef UIView<SlotProtocol> * _Nullable (^SlotProvider)(UIView *parentView);

双生命周期

插槽采用独立的 View 生命周期和 Data 生命周期：

┌─────────────────── 完整生命周期 ───────────────────┐
│                                                      │
│   ① onAttach:         ─── View 生命周期开始           │
│       ↓ 可访问 host、订阅通知、初始化子视图            │
│                                                      │
│   ② onBindData:       ─── Data 生命周期开始           │
│       ↓ 加载封面图、设置标题、配置场景行为             │
│                                                      │
│   ③ onUnbindData      ─── Data 生命周期结束           │
│       ↓ 清除图片缓存、重置 UI 状态                    │
│                                                      │
│   ④ onDetach          ─── View 生命周期结束           │
│       ↓ 取消通知订阅、移除定时器、释放所有资源         │
│                                                      │
└──────────────────────────────────────────────────────┘

继承BaseSlot（推荐）

BaseSlot 是所有 UI 插槽的推荐基类，封装了生命周期管理、通知订阅、场景适配等通用逻辑。

核心属性：

核心方法：

安全区域避让 （SlotSafeAreaEdge）

typedef NS_OPTIONS(NSUInteger, SlotSafeAreaEdge) {
    SlotSafeAreaEdgeNone   = 0,
    SlotSafeAreaEdgeTop    = 1 << 0,
    SlotSafeAreaEdgeLeft   = 1 << 1,
    SlotSafeAreaEdgeBottom = 1 << 2,
    SlotSafeAreaEdgeRight  = 1 << 3,
    SlotSafeAreaEdgeAll    = SlotSafeAreaEdgeTop | SlotSafeAreaEdgeLeft | SlotSafeAreaEdgeBottom | SlotSafeAreaEdgeRight,
};

SlotHostLayout 在 layoutSubviews 中根据 safeAreaEdges 收缩对应边的 frame，使插槽内部布局直接使用自身锚点即可避开刘海、Home Indicator 等区域。子类可在 initWithFrame: 中设置此属性。

延迟内容创建 （deferContentCreation）

设为 YES 时，onAttach: 不会调用 setupContentView，内容将在首次调用 show 或 ensureContentReady 时创建。适用于使用频率较低的插槽（如 SettingMenu），避免在初始化时创建不必要的视图。

- (instancetype)initWithFrame:(CGRect)frame {
    self = [super initWithFrame:frame];
    if (self) {
        self.deferContentCreation = YES;
    }
    return self;
}

自动隐藏延迟常量：

FOUNDATION_EXPORT const NSTimeInterval SlotAutoHideDelay;

控制栏自动隐藏类插槽（如 TopBar、BottomBar）在无交互后的隐藏延迟时间（秒）。

自定义插槽完整示例

1. 创建自定义插槽类，继承 BaseSlot：

   @interface MyCustomCoverSlot : BaseSlot
   
   @property (nonatomic, strong) UIImageView *coverImageView;
   @property (nonatomic, strong) UILabel *titleLabel;
   
   @end
   
   @implementation MyCustomCoverSlot
   
   - (instancetype)initWithFrame:(CGRect)frame {
       self = [super initWithFrame:frame];
       if (self) {
           // 可选：配置安全区域避让
           self.safeAreaEdges = SlotSafeAreaEdgeNone;
       }
       return self;
   }
   
   #pragma mark - 内容创建
   
   - (void)setupContentView {
       _coverImageView = [[UIImageView alloc] init];
       _coverImageView.contentMode = UIViewContentModeScaleAspectFill;
       _coverImageView.clipsToBounds = YES;
       [self addSubview:_coverImageView];
   
       _titleLabel = [[UILabel alloc] init];
       _titleLabel.textColor = [UIColor whiteColor];
       _titleLabel.font = [UIFont boldSystemFontOfSize:16];
       [self addSubview:_titleLabel];
   }
   
   #pragma mark - 生命周期
   
   - (void)onAttach:(id<SlotHost>)host {
       [super onAttach:host];
   }
   
   - (void)onBindData:(AliPlayerModel *)model {
       [super onBindData:model];
       if (model.coverUrl) {
           [_coverImageView sd_setImageWithURL:[NSURL URLWithString:model.coverUrl]];
       }
       _titleLabel.text = model.videoTitle;
       [self show];
   }
   
   - (void)onUnbindData {
       _coverImageView.image = nil;
       _titleLabel.text = nil;
       [super onUnbindData];
   }
   
   - (void)onDetach {
       [super onDetach];
   }
   
   #pragma mark - PlayerNotificationDelegate
   
   - (void)playerDidRenderFirstFrame {
       [self hideWithAnimation:YES];
   }
   
   - (void)playerDidChangeState:(PlayerState)state {
       if (state == PlayerStateError) {
           [self show];
       }
   }
   
   #pragma mark - 布局
   
   - (void)layoutSubviews {
       [super layoutSubviews];
       _coverImageView.frame = self.bounds;
       _titleLabel.frame = CGRectMake(16, self.bounds.size.height - 50,
                                      self.bounds.size.width - 32, 30);
   }
   
   @end

   说明

   BaseSlot 遵循 PlayerNotificationDelegate 协议，在 onAttach: 时自动注册为控制器的通知代理。子类直接实现感兴趣的回调方法即可接收播放器事件，无需手动订阅。

2. 注册并使用：

   SlotManager *slotManager = playerView.slotManager;
   [slotManager registerSlotType:SlotTypeCover provider:^UIView<SlotProtocol> *(UIView *parentView) {
       return [[MyCustomCoverSlot alloc] initWithFrame:parentView.bounds];
   }];
   [controller configure:model];
   [playerView attach:controller];

元素级可见性声明

子类通过 onRegisterElements 声明支持的元素及其默认可见性：

@implementation MyCustomTopBarSlot

- (NSUInteger)onRegisterElements {
    // 返回默认可见的元素位掩码
    // Back 和 Title 默认可见，Download 和 Snapshot 默认不可见
    return TopBarElementBack | TopBarElementTitle;
}

- (void)setupContentView {
    // 根据元素可见性决定是否创建 UI
    if ([self isElementVisible:TopBarElementBack]) {
        // 创建返回按钮
    }
    if ([self isElementVisible:TopBarElementDownload]) {
        // 创建下载按钮（默认不可见，但外部可通过 showElements 开启）
    }
}

@end

isElementVisible: 的合并逻辑如下：

• 外部调用 hideElements:forSlot: → 强制隐藏。

• 外部调用 showElements:forSlot: → 强制显示。

• 无外部覆盖时 → 使用 onRegisterElements 声明的默认值。

自定义插槽类型（CustomSlotType）

除内置插槽类型外，可通过 CustomSlotType 在任意位置插入自定义插槽：

// 在 TopBar(80) 和 BottomBar(90) 之间插入自定义插槽
CustomSlotType *type = [CustomSlotType typeWithKey:@"myCustomSlot" order:85];
[playerView.slotManager registerCustomSlotType:type provider:^UIView<SlotProtocol> *(UIView *parentView) {
    return [[MyCustomSlotView alloc] initWithFrame:parentView.bounds];
}];

// 检查自定义插槽是否已注册
BOOL registered = [playerView.slotManager isCustomSlotRegistered:type];

// 获取所有已注册的自定义插槽类型
NSArray<CustomSlotType *> *types = [playerView.slotManager customSlotTypes];

// 注销自定义插槽
[playerView.slotManager unregisterCustomSlotType:type];

在插槽中发送命令

插槽通过 host.controller 向控制器发送命令，实现单向数据流：

// 播放/暂停切换
- (void)onPlayPauseButtonTapped {
    AliPlayerController *controller = self.host.controller;
    if (controller.playerState == PlayerStatePlaying) {
        [controller pause];
    } else {
        [controller play];
    }
}

// 进度跳转
- (void)onSeekBarValueChanged:(UISlider *)slider {
    long position = (long)(slider.value * self.host.playerStateStore.duration);
    [self.host.controller seekTo:position];
}

// 全屏切换
- (void)onFullscreenButtonTapped {
    BOOL isFullscreen = self.host.viewState.isFullscreen;
    [self.host.controller setFullscreen:!isFullscreen];
}

SlotBehavior（组合模式）

SlotBehavior 采用组合模式设计，使非 UIView 对象也能获得插槽能力（生命周期管理、事件订阅）。适用于纯逻辑组件需要监听播放器事件的场景。

@interface MyAnalyticsTracker : NSObject <PlayerNotificationDelegate>

@property (nonatomic, strong) SlotBehavior *behavior;

@end

@implementation MyAnalyticsTracker

- (instancetype)init {
    self = [super init];
    if (self) {
        _behavior = [[SlotBehavior alloc] init];
    }
    return self;
}

- (void)attachToHost:(id<SlotHost>)host {
    [self.behavior attachToHost:host];
    // 通过 behavior 注册通知代理，detach 时自动取消订阅
    [self.behavior addNotificationDelegate:self toController:host.controller];
}

- (void)detach {
    [self.behavior detach];
}

#pragma mark - PlayerNotificationDelegate

- (void)playerDidRenderFirstFrame {
    // 上报首帧渲染事件
}

- (void)playerDidEncounterError:(NSError *)error {
    // 上报播放错误
}

@end

核心优势：通过 addNotificationDelegate:toController: 注册的所有代理，在 detach 时自动取消注册，避免手动管理订阅生命周期导致的内存泄漏。

槽位选择策略

请求创建插槽 → 自定义注册表中有该类型？
                  ├── 是 → 使用自定义实现
                  └── 否 → 默认注册表中有该类型？
                              ├── 是 → 使用默认实现
                              └── 否 → 跳过（不创建）

单向数据流

插槽系统采用单向数据流架构，插槽不直接持有控制器引用：

Controller → State / Event → Slot（状态下行，只读）
Slot → Command → Controller（命令上行，只发）

• 状态下行：通过 host.playerStateStore 主动查询，或通过 PlayerNotificationDelegate 回调被动接收。

• 命令上行：通过 host.controller 调用播放命令，由控制器执行。

插槽间隔离

插槽之间严禁直接获取对方实例或进行点对点通信。当一个插槽需要影响另一个插槽时：

1. 发起插槽通过 host.controller 发送状态变更。

2. Controller 通过 PlayerNotificationDelegate 通知所有关注此变化的插槽。

通过这种"事件上浮，状态下沉"的链路，避免了网状的 UI 耦合。

底部控制栏场景差异

核心协议与类

SlotManager方法速查