AliPlayerKit iOS API參考 - ApsaraVideo VOD

AliPlayerKit提供了豐富的API 介面，方便開發人員直接控制播放器的行為。本文檔提供AliPlayerKit iOS 版本主要介面的詳細說明。

說明

AliPlayerKit 為所有核心 API（含類與方法）提供了完善的代碼注釋。在 Xcode 中可通過 Quick Help（Option + Click）查看說明，以提升開發效率，同時也使 API 對 AI 編程工具更加友好。

核心類概覽

類名	類型	職責	生命週期
`AliPlayerKit`	全域入口	SDK 初始化、全域配置、工廠/預先載入器管理	App 生命週期
`AliPlayerView`	視圖容器	播放器視圖管理、插槽系統宿主	與 UIView 一致
`AliPlayerController`	播放控制器	播放控制、狀態管理、策略協調	手動 destroy 釋放
`AliPlayerModel`	資料模型	封裝視頻源和播放參數	值對象，無獨立生命週期
`PlayerStateStore`	狀態儲存	唯讀訪問播放器目前狀態	跟隨 Controller
`PlayerViewState`	檢視狀態	唯讀訪問 UI 層狀態（全屏、控制欄可見度）	跟隨 AliPlayerView
`SlotManager`	插槽管理器	插槽註冊、可見度控制、元素級管理	跟隨 AliPlayerView
`StrategyManager`	策略管理器	策略註冊/啟停/重設	跟隨 Controller
`StrategyRegistry`	策略註冊表	全域預設策略工廠管理（單例）	App 生命週期
`LogHub`	日誌中心	日誌輸出與觀察者管理（單例）	App 生命週期
`LocaleManager`	本地化管理	多語言支援與 Provider 注入（單例）	App 生命週期

AliPlayerKit（全域 API）

AliPlayerKit 是全域設定類，提供 SDK 初始化和全域配置能力。此類不可執行個體化，所有方法均為類方法。

初始化方法

方法	參數	傳回值	說明
`+ (void)setup`	-	void	初始化 SDK，內部 dispatch_once 保證等冪，建議在 App 啟動時調用。
`+ (BOOL)isInitialized`	-	BOOL	查詢是否已成功初始化。
`+ (void)setOnGlobalInitBlock:`	OnGlobalInitBlock block	void	設定全域初始化完成後的自訂配置回調，必須在 setup 之前調用。

狀態查詢與版本資訊

方法	參數	傳回值	說明
`+ (NSString *)getPlayerKitVersion`	-	NSString *	擷取 PlayerKit 版本號碼。
`+ (NSString *)getSdkVersion`	-	NSString *	擷取底層 AliPlayer SDK 版本號碼。

調試配置

方法	參數	傳回值	說明
`+ (void)setDebugModeEnabled:`	BOOL enabled	void	設定偵錯模式開關。
`+ (BOOL)isDebugModeEnabled`	-	BOOL	查詢偵錯模式是否開啟。
`+ (void)setLogPanelEnabled:`	BOOL enabled	void	設定日誌面板開關（僅調試情境啟用）。
`+ (BOOL)isLogPanelEnabled`	-	BOOL	查詢日誌面板是否啟用。

日誌配置

方法	參數	傳回值	說明
`+ (void)setLogLevel:`	LogLevel level	void	設定記錄層級，低於該層級的日誌被忽略（預設 Info）。
`+ (LogLevel)logLevel`	-	LogLevel	擷取當前記錄層級。
`+ (void)enableConsoleLog:`	BOOL enable	void	啟用/禁用控制台日誌輸出。
`+ (BOOL)isConsoleLogEnabled`	-	BOOL	查詢控制台日誌是否開啟。

播放器工廠

方法	參數	說明
`+ (void)setPlayerFactory:`	id<PlayerFactory> factory	設定自訂播放器工廠，傳 nil 恢複預設。
`+ (id<PlayerFactory>)playerFactory`	-	擷取當前播放器工廠。

預先載入

方法	參數	說明
`+ (void)setPreloader:`	id<PlayerPreloader> preloader	設定自訂預先載入器，傳 nil 恢複預設。
`+ (id<PlayerPreloader>)preloader`	-	擷取當前預先載入器。

緩衝管理

方法	說明
`+ (void)clearCaches`	清除播放器本地媒體緩衝，需在 setup 之後調用。

國際化

方法	參數	說明
`+ (void)setLanguageCode:`	NSString * languageCode	手動指定語言（支援 zh-Hans、en）。
`+ (void)setLocaleProvider:`	id<LocaleProvider> provider	注入自訂本地化 Provider（優先順序最高）。
`+ (void)resetLocaleToSystemLanguage`	-	重設為跟隨系統語言。
`+ (NSString *)currentLanguageCode`	-	擷取當前生效的語言代碼。

AliPlayerView（視圖 API）

AliPlayerView 是播放器視圖容器，負責管理控制器綁定和插槽系統。渲染視圖由內部 PlayerSurfaceSlot 建立並管理。

屬性

屬性	類型	說明
controller	AliPlayerController *	關聯的播放器控制器。
viewState	PlayerViewState *	跨視頻保留的 UI 狀態（全屏、控制欄可見度）。
slotManager	SlotManager *	插槽管理器，可在 attach 前預配置。
fullscreenTransition	id<FullscreenTransition>	全屏過渡動畫實現，預設使用獨立 Window 旋轉方案。
onBackPressed	void (^)(void)	返回鍵事件回調。

說明

onBackPressed 在非全屏狀態下觸發（全屏下返回操作由播放器內部自動處理，退出全屏）。若未設定此回調，播放器將通過 responder chain 嘗試預設導航行為（pop / dismiss）。

控制器綁定

方法	參數	說明
`- (void)attach:`	AliPlayerController * controller	綁定控制器並啟用插槽系統。
`- (void)detach`	-	解除綁定控制器，不銷毀 controller。

調用時機：

attach: ：在 controller 已調用 configure: 後綁定，插槽系統根據 slotManager 配置自動構建。
detach ：視圖即將銷毀或需換綁控制器時調用。

AliPlayerController（控制器 API）

AliPlayerController 是播放控制器，作為播放操作的統一入口，封裝播放器的建立、配置和控制邏輯。

屬性

屬性	類型	說明
playerModel	AliPlayerModel *	當前播放配置模型。
playerState	PlayerState	當前播放器狀態。
currentPosition	NSInteger	當前播放位置（毫秒）。
duration	NSInteger	視頻總時間長度（毫秒）。
stateStore	PlayerStateStore *	狀態儲存。
strategyManager	StrategyManager *	策略管理器。
lifecycleStrategy	id<PlayerLifecycleStrategy>	當前生命週期策略。
autoLifecycleManagement	BOOL	是否自動管理前後台生命週期（預設 YES）。
controlsVisibilityLocked	BOOL	控制欄可見度鎖定標誌。

說明

controlsVisibilityLocked 設為 YES 時，setControlsVisible:NO 請求會被忽略，控制欄持續保持可見狀態。用於進度條拖動等需要操作欄始終顯示的互動情境。

構造方法

方法	參數	說明
`- (instancetype)init`	-	使用預設生命週期策略建立控制器。
`- (instancetype)initWithLifecycleStrategy:`	`id<PlayerLifecycleStrategy>` strategy	使用自訂生命週期策略建立控制器。

配置與播放控制

方法	參數	說明
`- (void)configure:`	AliPlayerModel * model	配置播放器並準備播放。
`- (void)play`	-	開始或恢複播放。
`- (void)pause`	-	暫停播放。
`- (void)toggle`	-	切換播放/暫停狀態。
`- (void)replay`	-	從頭重新播放。
`- (void)stop`	-	停止播放。
`- (void)seekTo:`	NSInteger position（毫秒）	跳轉到指定位置。
`- (void)setRate:`	float rate	設定播放速度（1.0 正常）。
`- (void)setLoop:`	BOOL loop	設定是否迴圈播放。
`- (void)setMuted:`	BOOL muted	設定是否靜音。
`- (void)setMirrorMode:`	MirrorMode mirrorMode	設定鏡像模式。
`- (void)setScaleMode:`	ScaleMode scaleMode	設定縮放模式。
`- (void)setRotateMode:`	RotateMode rotateMode	設定旋轉角度。
`- (void)selectTrack:`	TrackQuality * quality	切換清晰度。
`- (void)snapshot`	-	截取當前視頻畫面。

UI 控制

方法	參數	傳回值	說明
`- (void)setControlsVisible:`	`BOOL` visible	`void`	設定控制欄可見度
`- (void)setFullscreen:`	`BOOL` fullscreen	`void`	設定全螢幕模式（帶動畫）
`- (void)setFullscreen:animated:`	`BOOL` fullscreen, `BOOL` animated	`void`	設定全螢幕模式（可選動畫）

生命週期方法

方法	參數	傳回值	說明
`- (void)onResume`	-	`void`	恢複播放（從後台回到前台時調用）。
`- (void)onPause`	-	`void`	暫停播放（進入後台時調用）。
`- (void)destroy`	-	`void`	銷毀播放器，釋放所有資源。

通知代理

方法	參數	傳回值	說明
`- (void)addNotificationDelegate:`	`id<PlayerNotificationDelegate>` delegate	`void`	添加通知代理（弱引用持有）
`- (void)removeNotificationDelegate:`	`id<PlayerNotificationDelegate>` delegate	`void`	移除通知代理

AliPlayerModel（模型 API）

AliPlayerModel 是播放器配置模型，封裝播放所需的全部配置資訊。

屬性

屬性	類型	預設值	說明
`videoSource`	`VideoSource *`	-	視頻資料來源（必填）。
`sceneType`	`SceneType`	`SceneTypeVOD`	播放情境類型。
`coverUrl`	`NSString *`	`nil`	封面圖 URL。
`videoTitle`	`NSString *`	`nil`	視頻標題。
`autoPlay`	`BOOL`	`YES`	是否自動播放。
`traceId`	`NSString *`	`nil`	跟蹤標識符（用於播放品質監控）。
`startTime`	`NSInteger`	`0`	起播位置（毫秒）。
`hardwareDecode`	`BOOL`	`YES`	是否啟用硬體解碼。
`allowScreenSleep`	`BOOL`	`NO`	是否允許螢幕休眠。
`disableScreenshot`	`BOOL`	`NO`	是否禁止截屏/錄屏。
`onPlayerConfigBlock`	`void (^)(id<MediaPlayer>)`	`nil`	執行個體級自訂配置回調。

建立方法

方法	參數	傳回值	說明
`- (instancetype)initWithVideoSource:`	`VideoSource *` videoSource	`AliPlayerModel *`	通過視頻源建立模型（指定初始化方法）。

通知系統

AliPlayerKit 採用 Dispatcher + Delegate 模式實現組件間的事件通訊。每個 AliPlayerController 持有獨立的 Dispatcher 執行個體，不同播放器執行個體的事件互不干擾。所有回調均在主線程派發。

PlayerNotificationDelegate（播放器通知代理）

播放器狀態變化回調協議，所有方法均為 @optional。

播放狀態

方法	參數	說明
`- playerDidChangeState:`	`PlayerState` state	播放器狀態變化。
`- playerDidPreparedWithDuration:`	`NSInteger` duration（毫秒）	準備完成，可開始播放。
`- playerDidRenderFirstFrame`	-	首幀渲染完成。
`- playerDidCompletion`	-	播放至達末尾。

播放進度

方法	參數	說明
`- playerDidUpdateCurrentPosition:duration:bufferedPosition:`	position, duration, bufferedPosition（毫秒）	定期報告播放進度。

錯誤與截圖

方法	參數	說明
`- playerDidEncounterError:`	`NSError *` error	播放錯誤。
`- playerDidCompleteSnapshot:`	`UIImage *`	截圖完成。

視頻資訊

方法	參數	說明
`- playerDidChangeVideoWidth:height:`	`NSInteger` width, height	視頻尺寸變化。

UI 狀態

方法	參數	說明
`- playerDidChangeFullscreen:`	`BOOL` isFullscreen	全屏狀態變化。
`- playerDidChangeControlsVisible:`	`BOOL` visible	控制欄可見度變化。

載入狀態

方法	參數	說明
`- playerDidLoadingBegin`	-	開始緩衝載入。
`- playerDidLoadingEnd`	-	緩衝載入結束。
`- playerDidUpdateLoadingProgress:`	`float` progress（0-100）	緩衝進度更新。

顯示模式

方法	參數	說明
`- playerDidChangeMirrorMode:`	`MirrorMode` mirrorMode	鏡像模式變化。
`- playerDidChangeScaleMode:`	`ScaleMode` scaleMode	縮放模式變化。
`- playerDidChangeRotateMode:`	`RotateMode` rotateMode	旋轉模式變化。

軌道

方法	參數	說明
`- playerDidTrackReady:`	`NSArray<TrackQuality > ` tracks	可用軌道資訊就緒。
`- playerDidTrackChanged:`	`TrackQuality *` quality	軌道切換完成。

GestureNotificationDelegate（手勢通知代理）

手勢互動事件回調協議，所有方法均為 @optional。由 GestureNotificationDispatcher 多播分發。

單擊

方法	參數	說明
`- gestureDidSingleTap`	-	單擊手勢觸發（通常用於切換控制欄顯隱）。

長按（倍速）

方法	參數	說明
`- gestureDidBeginLongPress`	-	長按開始（倍速播放啟用）。
`- gestureDidEndLongPress`	-	長按結束（倍速播放恢複）。

亮度（左側垂直拖動）

方法	參數	說明
`- gestureDidUpdateBrightnessWithPercent:`	`CGFloat` currentPercent（0.0~1.0）	亮度調節中。
`- gestureDidEndBrightnessAdjust`	-	亮度調節結束。

音量（右側垂直拖動）

方法	參數	說明
`- gestureDidUpdateVolumeWithPercent:`	`CGFloat` currentPercent（0.0~1.0）	音量大小中。
`- gestureDidEndVolumeAdjust`	-	音量大小結束。

SlotActionNotificationDelegate（插槽操作通知代理）

插槽間操作事件通知協議，用於解耦插槽之間的直接方法調用。所有方法均為 @optional，非同步派發到主線程。

方法	參數	說明
`- slotDidRequestToggleSettingMenu`	-	請求切換設定菜單顯隱（通常由 TopBarSlot 觸發）。
`- slotDidRequestShowSpeedPanel`	-	請求顯示倍速選擇面板（通常由 BottomBarSlot 觸發）。
`- slotDidRequestShowQualityPanel`	-	請求顯示畫質選擇面板（通常由 BottomBarSlot 觸發）。

播放器協議

AliPlayerKit 通過協議定義播放器的核心能力和行為約束。

MediaPlayer（播放器協議）

定義播放器核心操作介面，通過 PlayerFactory 建立執行個體。

屬性

屬性	類型	說明
`playerId`	`NSString *`（readonly）	播放器唯一標識
`state`	`PlayerState`（readonly）	當前播放狀態
`currentPosition`	`NSInteger`（readonly）	當前位置（毫秒）
`duration`	`NSInteger`（readonly）	總時間長度（毫秒）
`speed`	`float`（readonly）	當前播放速率
`loop`	`BOOL`（readonly）	是否迴圈
`muted`	`BOOL`（readonly）	是否靜音
`mirrorMode`	`MirrorMode`（readonly）	當前鏡像模式
`scaleMode`	`ScaleMode`（readonly）	當前縮放模式
`rotateMode`	`RotateMode`（readonly）	當前旋轉角度
`stateStore`	`PlayerStateStore *`（readonly）	狀態儲存
`playerView`	`UIView *`（nullable）	播放器渲染視圖，由生命週期策略在建立/回收時注入
`notificationDispatcher`	`PlayerNotificationDispatcher *`（nullable）	事件通知分發器

播放控制

方法	參數	說明
`- setDataSource:`	`AliPlayerModel *` model	設定視頻資料來源。
`- prepare`	-	非同步準備播放器資源。
`- start`	-	開始播放。
`- pause`	-	暫停。
`- toggle`	-	切換播放/暫停。
`- replay`	-	從頭重播。
`- seekTo:`	`NSInteger` position（毫秒）	跳轉到指定位置。
`- stop`	-	停止。
`- destroy`	-	銷毀播放器，釋放資源。

播放設定

方法	參數	說明
`- setSpeed:`	`float` speed	設定播放速率（0.5 ~ 2.0）。
`- setLoop:`	`BOOL` loop	設定迴圈播放。
`- setMuted:`	`BOOL` muted	設定靜音。
`- setMirrorMode:`	`MirrorMode` mode	設定鏡像模式。
`- setScaleMode:`	`ScaleMode` mode	設定縮放模式。
`- setRotateMode:`	`RotateMode` mode	設定旋轉角度。
`- selectTrack:`	`TrackQuality *` quality	切換清晰度。
`- snapshot`	-	截取當前幀。

PlayerLifecycleStrategy（生命週期策略協議）

定義播放器執行個體的擷取與回收行為。

方法

方法	參數	傳回值	說明
`- setupWithFactory:`	`id<PlayerFactory>` factory	`void`	注入播放器工廠（必須首先調用）。
`- acquirePlayer`	-	`id<MediaPlayer>`	擷取播放器執行個體。
`- recyclePlayer:force:`	player, `BOOL` force	`void`	回收播放器執行個體。
`- clear`	-	`void`	釋放所有緩衝執行個體。
`- preloadWithCount:`（@optional）	`NSInteger` count	`void`	預先載入指定數量執行個體到池中。
`- acquirePlayerWithUniqueId:`（@optional）	`NSString *` uniqueId	`id<MediaPlayer>`	按 ID 擷取（IdScoped 策略專用）。
`- recyclePlayer:uniqueId:force:`（@optional）	player, uniqueId, force	`void`	按 ID 回收（IdScoped 策略專用）。

內建策略實現

策略類	行為	適用情境
`DefaultLifecycleStrategy`	每次建立，回收即銷毀	普通視頻播放。
`SingletonLifecycleStrategy`	全域唯一執行個體（`sharedInstance` 單例）	列表播放、記憶體敏感情境。
`ReusePoolLifecycleStrategy`	LIFO 複用池	短視頻列表。
`IdScopedPoolLifecycleStrategy`	ID 綁定 + LRU 淘汰	視頻預先載入。

FullscreenTransition（全屏過渡協議）

定義播放器視圖進入/退出全屏的過渡行為。

方法 / 屬性	參數	說明
`- enterFullscreenWithPlayerView:animated:completion:`	playerView, animated, completion	進入全屏。
`- exitFullscreenWithPlayerView:animated:completion:`	playerView, animated, completion	退出全屏。
`isInFullscreen`（readonly）	-	當前是否處於全屏狀態。

預設實現 DefaultFullscreenTransition 採用獨立 Window 旋轉方案。可通過 playerView.fullscreenTransition 注入自訂實現。

插槽系統

插槽系統提供可組合、可替換的 UI 層級管理機制。

SlotProtocol（插槽協議）

定義插槽生命週期回調。

方法	參數	說明
`- onAttach:`	`id<SlotHost>` host	插槽掛載到宿主。
`- onDetach`	-	插槽從宿主分離。
`- onBindData:`	`AliPlayerModel *` model	播放資料繫結。
`- onUnbindData`	-	播放資料解除綁定。

BaseSlot（插槽基類）

所有內建插槽的抽象基類（UIView 子類），實現 SlotProtocol 協議並提供通用能力。

屬性

屬性	類型	說明
`host`	id<SlotHost>	所附屬的宿主。
`slotType`	SlotType	插槽類型標識（由 SlotHostLayout 注入）。
`safeAreaEdges`	SlotSafeAreaEdge	需要避讓的安全區域邊緣（預設 All）。
`deferContentCreation`	BOOL	延遲內容建立開關。
`contentReady`	BOOL	內容是否已就緒。
`touchPassthrough`	BOOL	觸摸穿透開關（預設 YES）。

方法

方法	類型	說明
`- setupContentView`	-	子類重寫以添加自訂 UI 元素。
`- show` / `- hide`	-	顯示/隱藏插槽。
`- showWithAnimation:` / `- hideWithAnimation:`	`BOOL` animated	帶動畫的顯示/隱藏。
`- isShowing`	-	返回當前是否可見。
`- dismiss`	-	通過宿主正確移除插槽。
`- onRegisterElements`	-	子類重寫聲明預設可見元素的位元遮罩。
`- isElementVisible:`	`NSUInteger` element	查詢指定元素的最終可見度。
`- currentSceneType`	-	安全讀取當前情境類型。
`- ensureContentReady`	-	確保延遲建立的內容已就緒。

SlotManager（插槽管理器）

SlotManager 是插槽系統的統一管理入口，通過 AliPlayerView.slotManager 擷取。

註冊方法

方法	參數	說明
`- registerSlotType:provider:`	type, `SlotProvider` block	註冊/替換插槽 Provider
`- unregisterSlotType:`	`SlotType` type	登出插槽 Provider
`- isRegistered:`	`SlotType` type	檢查是否登入
`- registerCustomSlotType:provider:`	`CustomSlotType *` type, provider	註冊自訂插槽
`- unregisterCustomSlotType:`	`CustomSlotType *` type	登出自訂插槽
`- isCustomSlotRegistered:`	`CustomSlotType *` type	檢查自訂插槽是否登入
`- customSlotTypes`	-	擷取所有登入的自訂插槽類型

插槽可見度

方法	參數	說明
`- hideSlot:`	`SlotType` type	隱藏整個插槽。
`- showSlot:`	`SlotType` type	顯示已隱藏的插槽。
`- isSlotHidden:`	`SlotType` type	檢查插槽是否隱藏。

情境可見度配置

方法	參數	傳回值	說明
`- registerSlotConfig:`	`SlotConfig *` config	`void`	為插槽類型註冊情境可見度配置（同類型已存在配置會被替換）
`- unregisterSlotConfigForType:`	`SlotType` slotType	`void`	移除指定插槽類型的情境可見度配置，移除後該插槽在所有情境下預設可見（僅受 `hideSlot:` 控制）
`- slotConfigForType:`	`SlotType` type	`nullable SlotConfig *`	擷取指定插槽類型的情境可見度配置，未配置返回 nil

元素級可見度

方法	參數	說明
`- hideElements:forSlot:`	`NSUInteger` mask, `SlotType` type	隱藏插槽內特定元素（位元遮罩）
`- showElements:forSlot:`	`NSUInteger` mask, `SlotType` type	顯示之前隱藏的元素
`- setHiddenElementMask:forSlot:`	`NSUInteger` mask, `SlotType` type	替換隱藏元素掩碼（覆蓋式）
`- hiddenElementMaskForSlot:`	`SlotType` type	擷取指定插槽的隱藏元素位元遮罩，無配置返回 0
`- shownElementMaskForSlot:`	`SlotType` type	擷取指定插槽的顯示元素位元遮罩，無配置返回 0
`- setAllHiddenElementMasks:`	`NSDictionary *` config	大量設定所有隱藏元素
`- clearAllElementMasks`	-	清空所有元素可見度配置

運行時訪問

方法	參數	傳回值	說明
`- slotViewForType:`	`SlotType` type	`UIView<SlotProtocol> *`	擷取已掛載的插槽視圖。
`- rebuildSlots`	-	`void`	重建所有插槽。
`- clearAll`	-	`void`	重設到初始狀態。

SlotType（插槽類型常量）

常量	值	說明
`SlotTypePlayerSurface`	10	播放器渲染視圖層（最底層）。
`SlotTypeGestureControl`	20	手勢識別和控制層。
`SlotTypeLandscapeHint`	30	橫屏提示層。
`SlotTypeCover`	40	視頻封面圖層。
`SlotTypeCenterDisplay`	50	中心展示層（倍速/亮度/音量）。
`SlotTypePlayState`	60	播放狀態指示層（載入/錯誤/完成）。
`SlotTypeLogPanel`	70	日誌面板層。
`SlotTypeTopBar`	80	頂部導覽列層。
`SlotTypeBottomBar`	90	底部控制欄層。
`SlotTypeSettingMenu`	100	設定菜單層。
`SlotTypeOptionPanel`	110	選項面板層（倍速/清晰度）。

CustomSlotType（自訂插槽類型）

用於在內建插槽之間插入業務自訂插槽。內建 SlotType 枚舉值按間隔 10 排列（10, 20, ...110），CustomSlotType 通過 order 欄位指定插入位置。

屬性 / 方法	說明
`key`	唯一標識，用於註冊、尋找和相等判斷。
`order`	排序值，決定插槽在 Z 軸上的位置（值越小越靠下）。
`+ typeWithKey:order:`	建立自訂插槽類型執行個體。

// 在 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];
}];

SlotElements（插槽元素位元遮罩）

配合 SlotManager 的 hideElements:forSlot: / showElements:forSlot: 方法使用，實現對插槽內單個 UI 元素的細粒度可見度控制。

TopBarElement（頂部欄元素）

常量	位	說明
`TopBarElementBack`	1 << 0	返回按鈕。
`TopBarElementTitle`	1 << 1	標題文本。
`TopBarElementDownload`	1 << 2	下載按鈕。
`TopBarElementSnapshot`	1 << 3	截圖按鈕。
`TopBarElementSettings`	1 << 4	設定按鈕。

BottomBarElement（底部欄元素）

常量	位	說明
`BottomBarElementPlay`	1 << 0	播放/暫停按鈕。
`BottomBarElementProgress`	1 << 1	進度條。
`BottomBarElementRefresh`	1 << 2	重新整理按鈕。
`BottomBarElementSpeed`	1 << 3	倍速按鈕（僅橫屏布局可見）。

SettingMenuElement（設定菜單元素）

常量	位	說明
`SettingMenuElementSpeed`	1 << 0	倍速選項。
`SettingMenuElementTrackInfo`	1 << 1	清晰度資訊。
`SettingMenuElementLoop`	1 << 2	迴圈播放。
`SettingMenuElementMute`	1 << 3	靜音。
`SettingMenuElementMirrorMode`	1 << 4	鏡像模式。
`SettingMenuElementRotateMode`	1 << 5	旋轉模式。
`SettingMenuElementScaleMode`	1 << 6	縮放模式。
`SettingMenuElementSubtitle`	1 << 7	字幕。

CenterDisplayElement（中心展示層元素）

常量	位	說明
`CenterDisplayElementVolume`	1 << 0	音量提示。
`CenterDisplayElementBrightness`	1 << 1	亮度提示。
`CenterDisplayElementSpeed`	1 << 2	倍速提示。

GestureElement（手勢控制元素）

說明

常量控制手勢互動的啟用與禁用，而非 UI 元素的顯隱。當某個手勢位被設定為隱藏時，對應的手勢將被禁用。

常量	位	說明
`GestureElementSingleTap`	1 << 0	單擊手勢。
`GestureElementDoubleTap`	1 << 1	雙擊手勢。
`GestureElementLongPress`	1 << 2	長按手勢。
`GestureElementHorizontalDrag`	1 << 3	水平拖動（進度）。
`GestureElementLeftVerticalDrag`	1 << 4	左側垂直拖動（亮度）。
`GestureElementRightVerticalDrag`	1 << 5	右側垂直拖動（音量）。

PlayStateElement（播放狀態層元素）

常量	位	說明
`PlayStateElementErrorMessage`	1 << 0	錯誤提示資訊。
`PlayStateElementLoadingMessage`	1 << 1	載入提示資訊。

狀態儲存

PlayerStateStore

PlayerStateStore 持有當前播放狀態的唯讀快照，通過 AliPlayerController.stateStore 擷取。

屬性	類型	預設值	說明
`playState`	`PlayerState`	`PlayerStateIdle`	當前播放狀態。
`duration`	`NSInteger`	0	總時間長度（毫秒）。
`currentPosition`	`NSInteger`	0	當前位置（毫秒）。
`bufferedPosition`	`NSInteger`	0	已緩衝位置（毫秒）。
`speed`	`float`	1.0	當前播放速度。
`loop`	`BOOL`	NO	是否迴圈。
`muted`	`BOOL`	NO	是否靜音。
`mirrorMode`	`MirrorMode`	`MirrorModeNone`	鏡像模式。
`scaleMode`	`ScaleMode`	`ScaleModeCenterCrop`	縮放模式。
`rotateMode`	`RotateMode`	`RotateModeDegree0`	旋轉角度。
`videoWidth`	`NSInteger`	0	視頻原始寬度。
`videoHeight`	`NSInteger`	0	視頻原始高度。
`trackQualityList`	`NSArray<TrackQuality > `	nil	可用清晰度列表。
`selectedTrackQuality`	`TrackQuality *`	nil	當前選中清晰度。

PlayerViewState

PlayerViewState 持有與 UI 層級相關的持久狀態，通過 AliPlayerView.viewState 擷取。跨視頻切換保留，狀態更新包含自動去重處理。

屬性 / 方法	類型	預設值	說明
`fullscreen`	`BOOL`（readonly）	`NO`	是否處於全螢幕模式。
`controlsVisible`	`BOOL`（readonly）	`NO`	控制欄是否可見。
`- reset`	-	-	重設所有狀態為預設值。
`- updateFullscreen:`	`BOOL` fullscreen	-	更新全屏狀態。
`- updateControlsVisible:`	`BOOL` controlsVisible	-	更新控制欄可見度。

視頻源

VideoSource（視頻源模型）

屬性	類型	說明
`sourceType`	`VideoSourceType`	視頻源類型。
`uniqueId`	`NSString *`	唯一標識（VidAuth/VidSts 返回 vid，URL 返回 url）。
`url`	`NSString *`	視頻 URL（URL 類型有效）。
`vid`	`NSString *`	視頻 ID（VidAuth/VidSts 有效）。
`playAuth`	`NSString *`	播放授權碼（VidAuth 有效）。
`accessKeyId`	`NSString *`	STS AccessKeyId。
`accessKeySecret`	`NSString *`	STS AccessKeySecret。
`securityToken`	`NSString *`	STS SecurityToken。
`region`	`NSString *`	地區標識。

Factory 方法

方法	參數	傳回值	說明
`+ vidAuthSourceWithVid:playAuth:`	vid, playAuth	`VideoSource *`	建立 VidAuth 視頻源（推薦）。
`+ vidStsSourceWithVid:accessKeyId:accessKeySecret:securityToken:region:`	vid, keyId, secret, token, region	`VideoSource *`	建立 VidSts 視頻源。
`+ urlSourceWithUrl:`	url	`VideoSource *`	建立 URL 視頻源。
`- (BOOL)isValid`	-	`BOOL`	驗證配置是否有效。

VideoSourceType（視頻源類型）

常量	值	說明
`VideoSourceTypeVidAuth`	0	VID + PlayAuth 播放憑證（推薦）。
`VideoSourceTypeVidSts`	1	VID + STS 臨時憑證。
`VideoSourceTypeUrl`	2	URL 直接播放。

策略系統

策略系統提供可插拔的播允許存取為擴充機制，策略名稱稱必須全域唯一。

StrategyProtocol（策略協議）

定義策略的生命週期契約，策略名稱稱必須全域唯一。

方法	參數	說明
`- strategyName`（@required）	-	策略唯一標識名稱。
`- strategyDidStart:`（@required）	`StrategyContext *` context	策略啟動，綁定播放器上下文。
`- strategyDidStop`（@required）	-	策略停止，解除綁定上下文。
`- strategyDidReset:`（@required）	`StrategyContext *` context	策略重設（視頻源切換時調用）。

StrategyContext（策略上下文）

為策略提供唯讀播放器環境資訊，在策略啟動時由 StrategyManager 建立並傳入。

屬性	類型	說明
`controller`	`AliPlayerController *`	關聯的播放器控制器。
`playerModel`	`AliPlayerModel *`	當前播放配置模型。
`stateStore`	`PlayerStateStore *`	播放器狀態儲存。

重要

此對象在 strategyDidStop 後不再有效，不應繼續使用。

BaseStrategy（策略基類）

策略抽象基類，實現 StrategyProtocol 和 PlayerNotificationDelegate，自動處理播放器事件的訂閱與取消訂閱。

屬性 / 方法	說明
`context`（readonly, nullable）	當前策略上下文（僅在 start 和 stop 之間有效）。
`- resetInternalState`	子類重設內部狀態的鉤子方法（如清零計數器、定時器）。

生命週期流轉：strategyDidStart: → 儲存上下文 → 註冊通知代理 → strategyDidReset: → 更新上下文 → 調用 resetInternalState → strategyDidStop → 登出通知代理 → 清空上下文。

說明

子類必須覆寫 strategyName 方法。如果覆寫 strategyDidStart: / strategyDidStop / strategyDidReset:，必須調用 super。

StrategyManager（策略管理器）

每個 AliPlayerController 擁有一個 StrategyManager 執行個體。策略按註冊順序執行，每個策略的生命週期調用均通過 @try/@catch 隔離。

方法

方法	參數	說明
`- registerStrategy:`	`id<StrategyProtocol>` strategy	註冊策略（同名策略會被停止並替換）。
`- unregisterStrategyWithName:`	`NSString *` name	按名稱登出策略。
`- strategyWithName:`	`NSString *` name	按名稱尋找策略。
`- startWithController:playerModel:`	controller, playerModel	啟動所有登入的策略。
`- resetWithPlayerModel:`	`AliPlayerModel *` playerModel	重設所有策略（視頻源切換時）。
`- stop`	-	停止所有策略。
`- destroy`	-	停止並移除所有策略。

屬性

屬性	類型	說明
`strategyCount`	`NSUInteger`	當前登入的策略數量。
`started`	`BOOL`	管理器是否已啟動。

StrategyRegistry（全域原則註冊表）

全域原則註冊表（單例），維護一組策略工廠 Block。每當新的 AliPlayerController 建立時，通過 applyToManager: 將所有登入的工廠執行個體化並注入到控制器的 StrategyManager 中。

方法	參數	說明
`+ sharedRegistry`	-	擷取全域註冊表單例。
`- addGlobalStrategyFactory:`	`StrategyFactory` factory	添加全域原則工廠。
`- clearGlobalStrategies`	-	移除所有全域原則工廠（包括內建策略）。
`- applyToManager:`	`StrategyManager *` manager	將所有全域原則執行個體化並註冊到指定管理器。
`- resetToDefault`	-	恢複為預設內建策略配置。

說明

內建策略（FirstFrameStrategy、StutterDetectStrategy、TrafficProtectionStrategy）在首次訪問時自動註冊。

內建策略

FirstFrameStrategy（首幀耗時監測）

測量從播放器開始準備到首幀渲染的時間，分為準備階段（Preparing 到 Prepared）和渲染階段（Prepared 到 FirstFrameRendered）。

屬性	類型	說明
`delegate`	`id<FirstFrameStrategyDelegate>`（weak）	回調代理

FirstFrameStrategyDelegate 回調：

方法	參數	說明
`- firstFrameStrategy:didRenderFirstFrameWithPrepareTime:renderTime:totalTime:`	strategy, prepareTimeMs, renderTimeMs, totalTimeMs	首幀渲染完成。

StutterDetectStrategy（卡頓檢測）

通過監聽 Loading 事件檢測卡頓（首幀渲染前的 Loading 不計入統計）。

屬性	類型	說明
`stutterCount`	`NSInteger`	當前會話的卡頓次數。
`totalStutterDurationMs`	`NSInteger`	當前會話的卡頓總時間長度（毫秒）。
`stutterThresholdMs`	`NSInteger`	卡頓閾值（毫秒），預設 0。
`delegate`	`id<StutterDetectStrategyDelegate>`	回調代理。
`- initWithThreshold:`	`NSInteger`	建立卡頓檢測策略（指定閾值）。

StutterDetectStrategyDelegate 回調：

方法	參數	說明
`- stutterDetectStrategy:didStutter:`	strategy, durationMs	檢測到一次卡頓
`- stutterDetectStrategy:didAnalyzeSession:validPlayDuration:totalStutterDuration:stutterCount:`	strategy, stayDurationMs, validPlayDurationMs, totalStutterDurationMs, stutterCount	播放會話分析完成

TrafficProtectionStrategy（流量保護）

監控網路狀態變化，檢測蜂窩網路播放。僅進行檢測和日誌記錄，不自動暫停播放。

屬性	類型	說明
`isOnCellularNetwork`	`BOOL`	當前是否處於蜂窩網路。
`delegate`	`id<TrafficProtectionStrategyDelegate>`	回調代理。

TrafficProtectionStrategyDelegate 回調：

方法	參數	說明
`- trafficProtectionStrategyDidDetectCellularNetwork:`	strategy	檢測到蜂窩網路播放。
`- trafficProtectionStrategyDidDetectWifiNetwork:`	strategy	檢測到網路切換回 Wi-Fi。

日誌系統

日誌系統提供統一的日誌輸出和觀察者註冊機制。

LogHub（日誌中心）

日誌管理中心（單例），統一管理日誌輸出和觀察者註冊。採用混合執行緒模式：控制台輸出在調用線程同步執行，觀察者通知非同步指派到後台串列隊列。

屬性

屬性	類型	預設值	說明
`logEnabled`	BOOL	YES	是否啟用日誌輸出。
`logLevel`	LogLevel	LogLevelInfo	最低日誌輸出層級。
`consoleLogEnabled`	BOOL	YES	是否啟用控制台（NSLog）輸出。

觀察者管理

方法	參數	說明
`+ sharedHub`	-	擷取 LogHub 共用單例。
`- addObserver:`	`id<LogObserver>` observer	添加日誌觀察者（弱引用持有）。
`- removeObserver:`	`id<LogObserver>` observer	移除日誌觀察者。

日誌輸出

方法	參數	說明
`- v:msg:`	tag, message	輸出 Verbose 層級日誌。
`- d:msg:`	tag, message	輸出 Debug 層級日誌。
`- i:msg:`	tag, message	輸出 Info 層級日誌。
`- w:msg:`	tag, message	輸出 Warn 層級日誌。
`- e:msg:`	tag, message	輸出 Error 層級日誌。
`- e:msg:error:`	tag, message, error（nullable）	輸出 Error 層級日誌（附帶錯誤對象）。
`- log:tag:msg:`	level, tag, message	按指定層級輸出日誌。

工具方法

方法	參數	傳回值	說明
`+ levelToString:`	`LogLevel` level	`NSString *`	將記錄層級轉換為縮寫字串（V/D/I/W/E/N）。
`+ stringToLevel:`	`NSString *` levelName	`LogLevel`	將層級名稱字串轉換回枚舉值。

LogObserver（日誌觀察者協議）

實現此協議可接收所有日誌輸出回調，用於自訂Tlog（如寫入檔案、上報伺服器）。

方法	參數	說明
`- onLog:`（@required）	`LogInfo *` logInfo	日誌輸出回調（在子線程執行）。

LogInfo（日誌資訊模型）

單條日誌條目的資料模型。

屬性	類型	說明
`level`	`LogLevel`	記錄層級。
`tag`	`NSString *`	日誌標籤。
`message`	`NSString *`	日誌訊息。
`timestamp`	`NSDate *`	時間戳記。
`threadName`	`NSString *`	線程名稱。
`fileName`	`NSString *`	源檔案名稱。
`line`	`NSInteger`	原始碼行號。
`error`	`NSError *`	關聯的錯誤對象。
`- formattedString`	-	擷取格式化的日誌字串。

預先載入系統

預先載入系統封裝播放器 SDK 的全域預先載入功能，通過 [AliPlayerKit preloader] 擷取。

PlayerPreloader（預先載入協議）

封裝播放器 SDK 的全域預先載入功能，通過 [AliPlayerKit preloader] 擷取。

方法	參數	傳回值	說明
`- addTask:delegate:`	task, delegate	`NSString *`（任務 ID）	添加預先載入任務。
`- cancelTask:`	`NSString *` taskId	`void`	取消指定任務。
`- pauseTask:`	`NSString *` taskId	`void`	暫停指定任務。
`- resumeTask:`	`NSString *` taskId	`void`	恢複指定任務。
`- cancelAll`	-	`void`	取消所有預先載入任務。

PlayerPreloadTask（預先載入任務）

屬性	類型	說明
`videoSource`	`VideoSource *`	視頻資料來源。
`preloadConfig`	`PlayerPreloadConfig *`	預先載入配置。
`- initWithVideoSource:preloadConfig:`	videoSource, preloadConfig	建立預先載入任務。

PlayerPreloadConfig（預先載入配置）

屬性	類型	預設值	說明
`preloadDuration`	`NSInteger`	3000	預先載入時間長度（毫秒）。
`loadStartPositionMs`	`NSInteger`	0	預先載入起始位置（毫秒）。
`defaultQuality`	`NSString *`	`@"AUTO"`	預設清晰度標識
`defaultResolution`	`NSInteger`	0	預設解析度（0 不限制）。
`defaultBandWidth`	`NSInteger`	0	預設碼率（0 不限制）。
`networkTimeout`	`NSInteger`	0	網路逾時時間（毫秒，0 使用 SDK 預設值）。
`networkRetryCount`	`NSInteger`	0	網路重試次數（0 使用 SDK 預設值）。
`referrer`	`NSString *`（nullable）	nil	Referrer 資訊。
`customHeaders`	`NSArray<NSString > `	nil	自訂要求標頭。

建立方法

方法	參數	說明
`- init`	-	使用預設配置建立。
`- initWithPreloadDuration:defaultQuality:`	preloadDuration, defaultQuality	指定預先載入時間長度和預設清晰度建立。

PreloadDelegate（預先載入代理）

接收預先載入任務的狀態事件。所有方法均為 @required。

說明

回調可能在後台線程觸發，上層需自行指派到主線程處理。

方法	參數	說明
`- preloadTaskDidComplete:source:`	taskId, source	預先載入任務完成。
`- preloadTaskDidFail:source:error:`	taskId, source, error	預先載入任務失敗。
`- preloadTaskDidCancel:source:`	taskId, source	預先載入任務被取消。

本地化系統

本地化系統管理 PlayerKit 的多語言支援，支援自動跟隨系統語言、手動指定、自訂 Provider 三種模式。

LocaleManager（本地化管理器）

本地化管理（單例），管理 PlayerKit 的多語言支援。

字串解析鏈（Resolution Chain）：Custom Provider（若已注入）→ 手動指定語言的 Bundle（Manual 模式）→ 跟隨系統語言的 SDK Bundle → 返回 key 本身作為 fallback。

屬性

屬性	類型	說明
`currentLanguageCode`	`NSString *`	當前生效的語言代碼。
`localeMode`	`LocaleMode`	當前語言模式。
`localeProvider`	`id<LocaleProvider>`	當前注入的自訂 Provider。

方法

方法	參數	說明
`+ sharedManager`	-	擷取單例執行個體。
`- setLanguageCode:`	`NSString *` languageCode	設定手動語言（切換為 Manual 模式）。
`- setLocaleProvider:`	`id<LocaleProvider>` provider	注入自訂 Provider（弱引用，傳 nil 移除）。
`- resetToSystemLanguage`	-	重設為跟隨系統語言。
`- localizedStringForKey:`	`NSString *` key	查詢本地化字串。

LocaleMode（語言模式）

常量	值	說明
`LocaleModeSystem`	0	跟隨系統語言（預設）。
`LocaleModeManual`	1	手動指定語言代碼。

LocaleProvider（本地化 Provider 協議）

宿主 App 可實現此協議，為 PlayerKit 提供自訂翻譯。

方法	參數	傳回值	說明
`- localizedStringForKey:`（@optional）	`NSString *` key	`NSString *`（nullable）	為指定 key 返回本地化字串（返回 nil 表示由 SDK 降級處理）

LocaleDidChangeNotification（語言變更通知）

當語言模式或語言代碼發生變化時，在主線程發送 LocaleDidChangeNotification 通知。userInfo 中通過 LocaleLanguageCodeKey 攜帶新的語言代碼。

關鍵枚舉與常量

AliPlayerKit 中使用的核心枚舉類型定義。

PlayerState（播放器狀態）

常量	值	說明
`PlayerStateIdle`	0	空閑（初始化完成但未載入資源）。
`PlayerStatePreparing`	1	準備中（非同步載入資源）。
`PlayerStatePrepared`	2	已準備（可以開始播放）。
`PlayerStatePlaying`	3	播放中。
`PlayerStatePaused`	4	已暫停。
`PlayerStateCompleted`	5	已完播。
`PlayerStateStopped`	6	已停止。
`PlayerStateError`	7	錯誤狀態。

SceneType（情境類型）

常量	值	說明
`SceneTypeVOD`	0	ApsaraVideo for VOD情境。
`SceneTypeLive`	1	直播情境。
`SceneTypeVideoList`	2	視頻列表/短視頻流情境。
`SceneTypeRestricted`	3	受限播放情境。
`SceneTypeMinimal`	4	極簡播放頁情境。

ScaleMode（縮放模式）

常量	值	說明
`ScaleModeFitXY`	0	展開填充視圖。
`ScaleModeFitCenter`	1	等比縮放適應視圖（可能留黑邊）。
`ScaleModeCenterCrop`	2	等比縮放裁剪填充。

MirrorMode（鏡像模式）

常量	值	說明
`MirrorModeNone`	0	無鏡像。
`MirrorModeHorizontal`	1	水平鏡像。
`MirrorModeVertical`	2	垂直鏡像。

RotateMode（旋轉模式）

常量	值	說明
`RotateModeDegree0`	0	0 度。
`RotateModeDegree90`	90	90 度。
`RotateModeDegree180`	180	180 度。
`RotateModeDegree270`	270	270 度。

LogLevel（記錄層級）

常量	值	說明
`LogLevelVerbose`	0	最詳細調試資訊。
`LogLevelDebug`	1	調試層級。
`LogLevelInfo`	2	資訊層級（預設）。
`LogLevelWarn`	3	警告層級。
`LogLevelError`	4	錯誤層級。
`LogLevelNone`	100	禁用所有日誌。

TrackType（軌道類型）

常量	值	說明
`TrackTypeUnknown`	0	未知。
`TrackTypeVideo`	1	視頻軌道。
`TrackTypeAudio`	2	音頻軌道。
`TrackTypeSubtitle`	3	字幕軌道。
`TrackTypeVOD`	4	VOD 軌道。

TrackQuality（軌道清晰度）

TrackQuality 描述一條可選的軌道（清晰度/音軌等），用於 selectTrack:、trackQualityList、selectedTrackQuality 等 API。

屬性	類型	說明
`index`	`NSInteger`（readonly）	軌道索引
`type`	`TrackType`（readonly）	軌道類型
`width`	`NSInteger`（readonly）	軌道寬度（像素）
`height`	`NSInteger`（readonly）	軌道高度（像素）
方法	參數	說明
`- initWithIndex:type:width:height:`	`NSInteger` index, `TrackType` type, `NSInteger` width, `NSInteger` height	構造方法