通知系统

什么是通知系统？

通知系统 (Notification System) 是 PlayerKit 内部的多播通知分发机制。每种 Dispatcher 管理一组弱引用观察者，通过对应的 Delegate 协议定义回调接口，观察者只需实现关心的方法即可接收对应通知。

核心特征：

• 多播分发：每个 Dispatcher 支持注册多个观察者，通知广播给所有已注册的观察者

• 弱引用管理：观察者通过 NSHashTable 以弱引用方式存储，对象释放后自动清理

• 实例级隔离：每个 AliPlayerController 持有独立的 Dispatcher 实例，不同播放器实例的通知互不干扰

• 异常隔离：每次观察者调用通过 @try/@catch 包裹，单个观察者异常不影响其他观察者

解决的问题

核心架构

PlayerKit 通知系统由三组 Dispatcher + Delegate 协议组成：

┌───────────────────────────────────────────────────────────────────┐
│                     AliPlayerController                            │
│                                                                   │
│  ┌─────────────────────────────────┐                              │
│  │ PlayerNotificationDispatcher    │──▶ PlayerNotificationDelegate │
│  └─────────────────────────────────┘                              │
│                                                                   │
│  ┌─────────────────────────────────┐                              │
│  │ GestureNotificationDispatcher   │──▶ GestureNotificationDelegate│
│  └─────────────────────────────────┘                              │
│                                                                   │
│  ┌─────────────────────────────────┐                              │
│  │ SlotActionNotificationDispatcher│──▶ SlotActionNotificationDele.│
│  └─────────────────────────────────┘                              │
└───────────────────────────────────────────────────────────────────┘
        │                   │                    │
        ▼                   ▼                    ▼
   [Observer A]        [Observer B]         [Observer C]
   (Slot/Strategy)     (Slot/Strategy)      (Slot/Strategy)

PlayerNotificationDispatcher

播放器核心通知分发器，负责将播放状态变化、进度更新、错误通知等信息分发给所有观察者。

核心属性与方法：

便捷分发方法（由 Controller 内部调用）：

GestureNotificationDispatcher

手势通知分发器，由 GestureControlSlot 创建并持有。在识别手势后，将手势语义信息分发给所有观察者。

核心方法：

特点：

• 回调参数聚焦于「显示所需的数据」（如亮度/音量百分比），而非手势的原始坐标信息。

• 由 SlotHostLayout 在插槽构建时注入到 TopBarSlot、BottomBarSlot、CenterDisplaySlot 等需要响应手势的插槽中。

SlotActionNotificationDispatcher

插槽操作通知分发器，由 SlotHostLayout 创建并管理。用于解耦插槽之间的直接方法调用（如 TopBarSlot / BottomBarSlot 触发 SettingMenuSlot）。

核心方法：

特点：与其他 Dispatcher 不同，SlotActionNotificationDispatcher 始终通过 dispatch_async(dispatch_get_main_queue(), ...) 异步分发通知，避免在按钮事件处理链中同步执行重量级 UI 操作导致的 UI 卡死。

通过Controller注册（推荐）

AliPlayerController 提供便捷方法注册 PlayerNotificationDelegate 观察者。这是最常用的订阅方式：

@interface MyViewController () <PlayerNotificationDelegate>
@property (nonatomic, strong) AliPlayerController *controller;
@end

@implementation MyViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    self.controller = [[AliPlayerController alloc] init];

    // 注册为通知观察者
    [self.controller addNotificationDelegate:self];

    // 配置并绑定播放器...
    [self.controller configure:model];
    [self.playerView attach:self.controller];
}

- (void)dealloc {
    // 推荐显式移除观察者
    [self.controller removeNotificationDelegate:self];
    [self.controller destroy];
}

#pragma mark - PlayerNotificationDelegate

- (void)playerDidChangeState:(PlayerState)state {
    // 更新播放/暂停按钮状态
}

- (void)playerDidUpdateCurrentPosition:(NSInteger)position
                              duration:(NSInteger)duration
                      bufferedPosition:(NSInteger)bufferedPosition {
    // 更新进度条
}

- (void)playerDidEncounterError:(NSError *)error {
    // 显示错误提示
}

@end

Controller 注册入口：

插槽内部通信（高级）

GestureNotificationDispatcher 和 SlotActionNotificationDispatcher 属于插槽内部通信机制，由 SlotHostLayout 在插槽构建时通过属性注入方式提供给内置插槽。

自定义插槽如需接收手势或插槽操作通知，可声明对应的 Dispatcher 属性，由 SlotHostLayout 注入后使用：

@interface MyCustomSlot : UIView <SlotProtocol, GestureNotificationDelegate, SlotActionNotificationDelegate>

@property (nonatomic, weak, nullable) GestureNotificationDispatcher *gestureDispatcher;
@property (nonatomic, weak, nullable) SlotActionNotificationDispatcher *slotActionDispatcher;

@end

@implementation MyCustomSlot

- (void)setGestureDispatcher:(GestureNotificationDispatcher *)gestureDispatcher {
    if (_gestureDispatcher) {
        [_gestureDispatcher removeObserver:self];
    }
    _gestureDispatcher = gestureDispatcher;
    if (_gestureDispatcher) {
        [_gestureDispatcher addObserver:self];
    }
}

- (void)setSlotActionDispatcher:(SlotActionNotificationDispatcher *)slotActionDispatcher {
    if (_slotActionDispatcher) {
        [_slotActionDispatcher removeObserver:self];
    }
    _slotActionDispatcher = slotActionDispatcher;
    if (_slotActionDispatcher) {
        [_slotActionDispatcher addObserver:self];
    }
}

#pragma mark - GestureNotificationDelegate

- (void)gestureDidSingleTap {
    // 单击切换控制栏显隐
}

- (void)gestureDidUpdateVolumeWithPercent:(CGFloat)currentPercent {
    // 显示音量调节 UI
}

#pragma mark - SlotActionNotificationDelegate

- (void)slotDidRequestToggleSettingMenu {
    // 响应设置菜单切换请求
}

@end

完整代码示例

以下展示一个完整的播放页面如何订阅播放器通知：

@interface PlayerPageViewController () <PlayerNotificationDelegate>
@property (nonatomic, strong) AliPlayerView *playerView;
@property (nonatomic, strong) AliPlayerController *controller;
@end

@implementation PlayerPageViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    self.playerView = [[AliPlayerView alloc] initWithFrame:self.view.bounds];
    [self.view addSubview:self.playerView];

    self.controller = [[AliPlayerController alloc] init];

    // 注册为通知观察者
    [self.controller addNotificationDelegate:self];

    VideoSource *source = [VideoSource vidAuthSourceWithVid:@"vid" playAuth:@"auth"];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
    [self.controller configure:model];
    [self.playerView attach:self.controller];
}

- (void)dealloc {
    [self.controller removeNotificationDelegate:self];
    [self.controller destroy];
}

#pragma mark - PlayerNotificationDelegate

- (void)playerDidChangeState:(PlayerState)state {
    NSLog(@"播放状态变化: %ld", (long)state);
}

- (void)playerDidPreparedWithDuration:(NSInteger)duration {
    NSLog(@"准备完成，总时长: %ld ms", (long)duration);
}

- (void)playerDidRenderFirstFrame {
    // 隐藏封面图
}

- (void)playerDidCompletion {
    // 显示重播按钮
}

- (void)playerDidUpdateCurrentPosition:(NSInteger)position
                              duration:(NSInteger)duration
                      bufferedPosition:(NSInteger)bufferedPosition {
    // 更新进度条
}

- (void)playerDidChangeFullscreen:(BOOL)isFullscreen {
    // 更新全屏/非全屏布局
}

- (void)playerDidChangeControlsVisible:(BOOL)visible {
    // 同步控制栏显隐
}

- (void)playerDidEncounterError:(NSError *)error {
    NSLog(@"播放错误: %@", error.localizedDescription);
}

@end

PlayerNotificationDelegate（18个@optional方法）

播放状态通知

播放进度通知

错误通知

截图通知

视频尺寸通知

全屏和控制栏通知

加载通知

显示模式通知

轨道通知

GestureNotificationDelegate（7个@optional方法）

SlotActionNotificationDelegate（3个@optional方法）

设计原理

在多播放器实例场景（如短视频上下滑、画中画）中，不同播放器产生的通知必须互不干扰。PlayerKit 通过实例粒度而非全局过滤实现通知隔离。

隔离方式

每个 AliPlayerController 持有独立的 PlayerNotificationDispatcher 实例。观察者注册到某个 Controller 的 Dispatcher 后，只会接收该 Controller 产生的通知：

┌── AliPlayerController (A) ──┐     ┌── AliPlayerController (B) ──┐
│  PlayerNotificationDispatcher │     │  PlayerNotificationDispatcher │
│  ├── Observer 1               │     │  ├── Observer 3               │
│  └── Observer 2               │     │  └── Observer 4               │
└───────────────────────────────┘     └───────────────────────────────┘

Observer 1/2 只收到 Controller A 的通知
Observer 3/4 只收到 Controller B 的通知

关键设计：

• 无需全局 EventBus，无需在回调中手动判断 playerId。

• PlayerNotificationDispatcher.playerId 属性用于让观察者获知通知来源标识，而非用于过滤。

• 注册即隔离，解除注册即断开。

// Controller A 的通知只分发给注册到 A 的观察者
[controllerA addNotificationDelegate:slotA];  // slotA 只收到 A 的通知
[controllerB addNotificationDelegate:slotB];  // slotB 只收到 B 的通知

实现Delegate协议

实现所需的 Delegate 协议，只需实现关心的方法（所有方法均为 @optional）：

@interface MyAnalyticsObserver : NSObject <PlayerNotificationDelegate>
@end

@implementation MyAnalyticsObserver

- (void)playerDidChangeState:(PlayerState)state {
    [self trackStateChange:state];
}

- (void)playerDidEncounterError:(NSError *)error {
    [self reportError:error];
}

- (void)playerDidCompletion {
    [self trackPlaybackComplete];
}

@end

注册与注销

// 创建观察者
MyAnalyticsObserver *observer = [[MyAnalyticsObserver alloc] init];

// 注册：通过 Controller 便捷入口
[controller addNotificationDelegate:observer];

// 注销：显式移除
[controller removeNotificationDelegate:observer];

线程安全机制

分发流程：

PlayerNotificationDispatcher / GestureNotificationDispatcher：
    dispatch 方法调用
        → 串行队列内获取观察者快照（线程安全）
        → 主线程上逐个调用观察者回调
        → 每次调用 @try/@catch 包裹（异常隔离）

SlotActionNotificationDispatcher：
    notifyObservers: 调用
        → 串行队列内获取观察者快照（线程安全）
        → dispatch_async(dispatch_get_main_queue(), ...) 异步分发
        → 下一个 RunLoop 逐个调用观察者回调
        → 每次调用 @try/@catch 包裹（异常隔离）

Dispatcher类

Delegate协议

Controller协议

通用Dispatcher方法

PlayerNotificationDispatcher专有方法