@quicktvui/ai 1.0.0

package/rules/.docs/zh-CN/component/player-manager/introduction.md

@@ -0,0 +1,207 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# ESPlayerManager 简介
+
+播放管理器`ESPlayerManager`是基于常用的应用业务封装的一套管理播放组件的组件。
+
+***`ESPlayerManager`组件用来管理各个播放器组件，本身不提供播放功能。***
+
+除了基本的播放控制功能外，还提供以下功能：
+
+* 播放窗口切换
+* 播放模式
+* 多类型播放器混播
+* 广告
+
+## 结构示意图
+
+<img src="/component/player-manager/structure.png" />
+
+## API
+
+### DataStructure
+
+#### ESMediaItem
+
+媒资条目
+
+| Name          | Description                | Type                          |   Default   |
+| -------------- | ------------------| ----------------------------|---------|
+| [type](/zh-CN/component/player-manager/player-type)    | [播放器的类型](/zh-CN/component/player-manager/player-type)        | ^[number]                   |   `1`    |
+| id             | 媒资的唯一标识符     | ^[number] / ^[string]            |   -    |
+| mediaSourceList| 媒资资源列表        | ^[ESMediaSourceList]         |   -    |
+| interceptors   | 媒资条目拦截器      | ^[Array<ESIPlayerInterceptor>] |   -   |
+| position       | 媒资播放位置        | ^[ESPlayerPosition]             |   -    |
+| metadata       | 媒资信息           | ^[ESMediaMetadata]             |   -    |
+| previousRollADList| 前贴片广告资源列表| ^[ESMediaSourceList]          |   -    |
+| middleRollADList| 中插广告资源列表   | ^[ESMediaSourceList]          |   -    |
+| postRollADList | 后贴广告资源列表     | ^[ESMediaSourceList]          |   -    |
+| adPlayerType   | 广告播放器类型       | ^[number]                    |   -    |
+
+#### ESMediaItemList
+
+媒资条目列表
+
+| Name          | Description                | Type                          |   Default   |
+| -------------- | ------------------| ----------------------------|---------|
+| index          | 默认播放媒资条目的索引| ^[number]                    |   -    |
+| list           | 媒资条目列表        | ^[Array<ESMediaItem>]          |   -    |
+| interceptors   | 媒资条目列表拦截器   | ^[Array<ESIPlayerInterceptor>] |   -    |
+| metadata       | 媒资信息           | ^[ESMediaMetadata]             |   -    |
+
+### Attributes
+
+| Name                      | Description          | Type                           |  Default   |
+| -------------------------| --------------------- | ----------------------------- |---------|
+| playerList               | 播放器数组列表          | ^[Array<ESIPlayer>]            |[]    |
+| playerViewList           | 播放器视图数组列表       | ^[Array<ESIPlayerManagerView>] |[]    |
+| adPlayerList             | 广告播放器数组列表       | ^[Array<ESIPlayer]            |
+| adPlayerViewList         | 广告播放器视图数组列表    | ^[Array<ESIPlayerManagerView>] |[]    |
+| adChannel                | 广告的渠道              | ^[string]                      |''    |
+| adDebug                  | 是否开启广告调试模式      | ^[boolean]                     |false  |
+| adTest                   | 是否开启广告测试环境      | ^[boolean]                     |false  |
+| playMediaAuto            | 是否自动播放媒资         | ^[boolean]                     |true    |
+| playMediaSourceAuto      | 是否自动播放媒资数据源    | ^[boolean]                     |true    |
+| playMediaSourceListMode  | 媒资数据源播放模式       | ^[ESPlayerPlayMode]             |ES_PLAYER_PLAY_MODE_ONCE    |
+| playerBackgroundColor    | 播放管理器背景颜色       | ^[string]                       |transparent    |
+| smallWindowWidth         | 播放小窗口模式宽度       | ^[number]                       |976    |
+| smallWindowHeight        | 播放小窗口模式高度       | ^[number]                       |557    |
+| fullWindowWidth          | 播放全屏窗口模式宽度      | ^[number]                      |1920    |
+| fullWindowHeight         | 播放全屏窗口模式高度      | ^[number]                      |1080    |
+| floatWindowWidth         | 播放浮动窗口模式宽度      | ^[number]                      |400    |
+| floatWindowHeight        | 播放浮动窗口模式高度      | ^[number]                      |230    |
+| initPlayerWindowType     | 初始化播放窗口模式        | ^[ESPlayerWindowType]          |ES_PLAYER_WINDOW_TYPE_SMALL    |
+| isEnabled                | 播放管理器是否可用        | ^[boolean]                     |true    |
+
+### Events
+
+| Name                          | Description           | Type                                                                                                      |
+| ----------------------------- | --------------------  | --------------------------------------------------------------------------------------------------------- |
+| onPlayerInitialized           | 播放器初始化事件          | ^[Function]`onPlayerInitialized() => void`                                |
+| onPlayerPlayMediaSourceList   | 播放媒资资源列表事件      | ^[Function]`onPlayerPlayMediaSourceList(mediaSourceList: ESMediaSourceList) => void`         |
+| onPlayerPlayMediaSource       | 播放媒资资源事件         | ^[Function]`onPlayerPlayMediaSource(mediaSource: ESMediaSource) => void`                      |
+| onPlayerInterceptSuccess      | 播放拦截器成功事件         | ^[Function]`onPlayerInterceptSuccess(result: ESPlayerInterceptResult) => void`                      |
+| onPlayerInterceptError        | 播放拦截器错误事件         | ^[Function]`onPlayerInterceptError(error: ESPlayerInterceptError) => void`                      |
+| onPlayerSizeChanged           | 播放器尺寸变化事件         | ^[Function]`onPlayerSizeChanged(playerWidth: number, playerHeight: number) => void`                      |
+| onPlayerPreparing             | 播放器准备中事件         | ^[Function]`onPlayerPreparing() => void`                      |
+| onPlayerPrepared              | 播放器准备好事件         | ^[Function]`onPlayerPrepared() => void`                      |
+| onPlayerBufferStart           | 播放器开始缓冲事件         | ^[Function]`onPlayerBufferStart() => void`                      |
+| onPlayerBufferEnd             | 播放器缓冲结束事件         | ^[Function]`onPlayerBufferEnd() => void`                      |
+| onPlayerPlaying               | 播放器开始播放事件         | ^[Function]`onPlayerPlaying() => void`                      |
+| onPlayerProgressChanged       | 播放进度事件         | ^[Function]`onPlayerProgressChanged(progress: number) => void`                      |
+| onPlayerDurationChanged       | 播放总长度事件         | ^[Function]`onPlayerDurationChanged(duration: number) => void`                      |
+| onPlayerSeekStart             | 播放器开始快进事件         | ^[Function]`onPlayerSeekStart() => void`                      |
+| onPlayerSeekCompleted         | 播放器快进结束事件         | ^[Function]`onPlayerSeekCompleted() => void`                      |
+| onPlayerPaused                | 播放器暂停播放事件         | ^[Function]`onPlayerPaused() => void`                      |
+| onPlayerResumed               | 播放器恢复播放事件         | ^[Function]`onPlayerResumed() => void`                      |
+| onPlayerStopped               | 播放器停止播放事件         | ^[Function]`onPlayerStopped() => void`                      |
+| onPlayerCompleted             | 播放器播放完毕事件         | ^[Function]`onPlayerCompleted() => void`                      |
+| onPlayerError                 | 播放错误事件         | ^[Function]`onPlayerError(error: ESPlayerError) => void`                      |
+| onPlayerInfo                  | 播放信息事件         | ^[Function]`onPlayerInfo(info: ESPlayerInfo) => void`                      |
+| onPlayerNoMediaSourceCanPlay  | 无媒资资源可播放事件         | ^[Function]`onPlayerNoMediaSourceCanPlay(next: boolean) => void`                      |
+| onPlayerVolumeChanged         | 播放器音量变化事件         | ^[Function]`onPlayerVolumeChanged(leftVolume: number, rightVolume: number) => void`                      |
+| onPlayerLeftVolumeChanged     | 播放器左声道音量变化事件         | ^[Function]`onPlayerLeftVolumeChanged(volume: number) => void`                      |
+| onPlayerRightVolumeChanged    | 播放器右声道音量变化事件         | ^[Function]`onPlayerRightVolumeChanged(volume: number) => void`                      |
+| onPlayerDefinitionListChanged | 播放器媒资清晰度列表事件         | ^[Function]`onPlayerDefinitionListChanged(definitionList: Array<ESPlayerDefinition>) => void`                      |
+| onPlayerDefinitionChanged     | 播放器媒资清晰度事件         | ^[Function]`onPlayerDefinitionChanged(definition: ESPlayerDefinition) => void`                      |
+| onPlayerPlayRateListChanged   | 播放速率列表事件         | ^[Function]`onPlayerPlayRateListChanged(rateList: Array<ESPlayerRate>) => void`                      |
+| onPlayerPlayRateChanged       | 播放速率事件         | ^[Function]`onPlayerPlayRateChanged(rate: ESPlayerRate) => void`                      |
+| onPlayerDecodeListChanged     | 播放器解码方式列表事件         | ^[Function]`onPlayerDecodeListChanged(decodeList: Array<ESPlayerDecode>) => void`                      |
+| onPlayerDecodeChanged         | 播放器解码方式事件         | ^[Function]`onPlayerDecodeChanged(decode: ESPlayerDecode) => void`                      |
+| onPlayerAspectRatioListChanged| 画面比例列表事件         | ^[Function]`onPlayerAspectRatioListChanged(aspectRatioList: Array<ESPlayerAspectRatio>) => void`                      |
+| onPlayerAspectRatioChanged    | 画面比例事件         | ^[Function]`onPlayerAspectRatioChanged(aspectRatio: ESPlayerAspectRatio) => void`                      |
+| onPlayerPlayMediaSourceListModeListChanged    | 播放媒资资源列表模式列表事件         | ^[Function]`onPlayerPlayMediaSourceListModeListChanged(playModeList: Array<ESPlayerPlayMode>) => void`                      |
+| onPlayerPlayMediaSourceListModeChanged    | 播放媒资资源列表模式事件         | ^[Function]`onPlayerPlayMediaSourceListModeChanged(playMode: ESPlayerPlayMode) => void`                      |
+| onPlayerRenderListChanged     | 渲染模式列表事件         | ^[Function]`onPlayerRenderListChanged(renderList: Array<ESPlayerRender>) => void`                      |
+| onPlayerRenderChanged         | 渲染模式事件         | ^[Function]`onPlayerRenderChanged(render: ESPlayerRender) => void`                      |
+| onPlayerViewSizeChanged       | 播放器尺寸变化事件         | ^[Function]`onPlayerViewSizeChanged(playerWidth: number, playerHeight: number) => void`                      |
+| onPlayerViewChanged           | 播放器视图变化事件         | ^[Function]`onPlayerViewChanged() => void`                      |
+| onPlayerClickable             | 播放器视图可点击事件         | ^[Function]`onPlayerClickable(playerClickable: boolean) => void`                      |
+| onPlayerPlayMediaList         | 播放媒资条目列表事件         | ^[Function]`onPlayerPlayMediaList(playList: ESMediaItemList) => void`                      |
+| onPlayerMediaListInitialized  | 初始化媒资条目列表事件         | ^[Function]`onPlayerMediaListInitialized(mediaList: SparseArray<ESMediaItem>) => void`                      |
+| onPlayerPlayMedia             | 播放媒资条目事件         | ^[Function]`onPlayerPlayMedia(mediaItem: ESMediaItem) => void`                      |
+| onPlayerInterceptSuccess      | 播放拦截器成功事件         | ^[Function]`onPlayerInterceptSuccess(result: ESPlayerInterceptResult) => void`                      |
+| onPlayerInterceptError        | 播放拦截器错误事件         | ^[Function]`onPlayerInterceptError(error: ESPlayerInterceptError) => void`                      |
+| onPlayerNoMediaCanPlay        | 无媒资可播放事件         | ^[Function]`onPlayerNoMediaCanPlay(next: boolean) => void`                      |
+| onPlayerPlayMediaListModeListChanged        | 播放媒资列表模式列表事件         | ^[Function]`onPlayerPlayMediaListModeListChanged(playModeList: Array<ESPlayerPlayMode>) => void`                      |
+| onPlayerPlayMediaListModeChanged        | 播放媒资列表模式事件         | ^[Function]`onPlayerPlayMediaListModeChanged(playMode: ESPlayerPlayMode) => void`                      |
+| onPlayerPlayMediaSourceListModeListChanged        | 播放媒资资源列表模式列表事件         | ^[Function]`onPlayerPlayMediaSourceListModeListChanged(playModeList: Array<ESPlayerPlayMode>) => void`                      |
+| onPlayerPlayMediaSourceListModeChanged        | 播放媒资资源列表模式事件         | ^[Function]`onPlayerPlayMediaSourceListModeChanged(playMode: ESPlayerPlayMode) => void`                      |
+| onPlayerWindowTypeChanged        | 播放管理器窗口变化事件         | ^[Function]`onPlayerWindowTypeChanged(windowType: ESPlayerWindowType) => void`                      |
+
+### Exposes
+
+| Name                             | Description                 | Type                                                                              |
+| -------------------------------- | --------------------------- | --------------------------------------------------------------------------------- |
+| initialize                       | 初始化                       | ^[Function]`() => void`                                                    |
+| isInitialized                    | 判断播放管理器是否初始化         | ^[Function]`() => boolean`                                             |
+| setVisible                       | 设置播放管理器是否可见          | ^[Function]`(value: boolean) => void`                                       |
+| playMediaSourceList              | 播放媒资资源列表               | ^[Function]`(mediaSourceList: ESMediaSourceList) => void`         |
+| playMediaSourceByIndex           | 根据媒资资源索引进行播放         | ^[Function]`(index: number) => void`                           |
+| playMediaSourceById              | 根据媒资资源唯一标识符进行播放    | ^[Function]`(id: string) => void`                                  |
+| playMediaSource                  | 播放媒资资源                  | ^[Function]`(mediaSource: ESMediaSource) => void`                       |
+| playNextMediaSource              | 播放下一个媒资资源             | ^[Function]`() => void`                                             |
+| playPreviousMediaSource          | 播放上一个媒资资源             | ^[Function]`() => void`                                         |
+| getMediaSourceList               | 获取正在播放的媒资资源列表       | ^[Function]`() => Array<ESMediaSource> \| null`                     |
+| getMediaSource                   | 根据媒资资源索引获取媒资资源     | ^[Function]`(index: number) => ESMediaSource \| null`                    |
+| getPlayingMediaSourceIndex       | 获取正在播放的媒资资源的索引     | ^[Function]`() => number`                                    |
+| getPlayingMediaSourceList        | 获取正在播放的媒资资源列表       | ^[Function]`() => ESMediaSourceList \| null`                  |
+| getPlayingMediaSource            | 获取正在播放的媒资资源          | ^[Function]`() => ESMediaSource \| null`                          |
+| play                             | 播放器的播放方法               | ^[Function]`(...params: Array<any>) => void`                                       |
+| start                            | 播放器的开始播放方法            | ^[Function]`(position: number) => void`                                           |
+| pause                            | 播放器的暂停播放方法            | ^[Function]`() => void`                                                           |
+| resume                           | 恢复播放器播放                 | ^[Function]`() => void`                                                          |
+| stop                             | 停止播放器播放                 | ^[Function]`() => void`                                                            |
+| reset                            | 重置播放器                    | ^[Function]`() => void`                                                           |
+| release                          | 回收播放器资源                 | ^[Function]`() => void`                                                         |
+| seekTo                           | 播放快进                      | ^[Function]`(progress: number) => void`                                          |
+| getDuration                      | 获取播放总时长                 | ^[Function]`() => void`                                                     |
+| getCurrentPosition               | 获取当前播放的进度              | ^[Function]`() => void`                                              |
+| setSize                          | 设置播放器的尺寸                | ^[Function]`(width: number, height: number) => void`                            |
+| setPlayRate                      | 设置播放速率                   | ^[Function]`(playRate: ESPlayerRate) => void`                               |
+| setPlayMode                      | 设置播放模式                   | ^[Function]`(playMode: ESPlayerPlayMode) => void`                           |
+| setDefinition                    | 设置播放媒资清晰度              | ^[Function]`(definition: ESPlayerDefinition) => void`                     |
+| setCache                         | 设置播放缓存策略                | ^[Function]`(cache: ESPlayerCache) => void`                                    |
+| setDecode                        | 设置播放解码方式                | ^[Function]`(decode: ESPlayerDecode) => void`                                 |
+| setRender                        | 设置播放渲染方式                | ^[Function]`(render: ESPlayerRender) => void`                                 |
+| setAspectRatio                   | 设置播放画面比例                | ^[Function]`(aspectRatio: ESPlayerAspectRatio) => void`                  |
+| getLeftVolume                    | 获取左声道音量                  | ^[Function]`() => void`                                                   |
+| getRightVolume                   | 获取右声道音量                  | ^[Function]`() => void`                                                  |
+| setLeftVolume                    | 设置左声道音量                  | ^[Function]`(leftVolume: number) => void`                                 |
+| setRightVolume                   | 设置右声道音量                  | ^[Function]`(rightVolume: number) => void`                               |
+| setVolume                        | 设置左右声道音量                 | ^[Function]`(volume: number) => void`                                        |
+| getVolume                        | 获取音量                       | ^[Function]`() => void`                                                       |
+| setStopped                       | 设置播放管理器的停止状态          | ^[Function]`(stopped: boolean) => void`                                      |
+| setEnabled                       | 设置播放管理器的可用状态          | ^[Function]`(enabled: boolean) => void`                                      |
+| setProgressCallback              | 设置播放进度回调                 | ^[Function]`(callback: ESPlayerProgressCallback) => void`          |
+| setDurationCallback              | 设置播放总进度回调               | ^[Function]`(callback: ESPlayerDurationCallback) => void`           |
+| invalidate                       | 刷新播放视图                    | ^[Function]`() => void`                                                      |
+| playMediaList                    | 播放媒资列表                    | ^[Function]`(playList: ESMediaItemList) => void`                                                      |
+| playMediaByIndex                 | 播放指定索引的媒资               | ^[Function]`(index: number) => void`                                                      |
+| playMediaById                    | 播放指定唯一标识符的媒资          | ^[Function]`(id: string) => void`                                                      |
+| playMedia                        | 播放媒资                       | ^[Function]`(mediaItem: ESMediaItem) => void`                                                      |
+| addMediaToLast                   | 添加媒资列表到播放列表的末尾       | ^[Function]`(mediaItemList: Array<ESMediaItem>) => void`                                                      |
+| addMediaToFirst                  | 添加媒资列表到播放列表的首位       | ^[Function]`(mediaItemList: Array<ESMediaItem>) => void`                                                      |
+| addMediaToIndex                  | 添加媒资列表到播放列表的指定位置    | ^[Function]`(index: number, mediaItemList: Array<ESMediaItem>) => void`                                                      |
+| replaceMedia                     | 替换媒资列表指定位置媒资          | ^[Function]`(beginIndex: number, mediaItemList: Array<ESMediaItem>) => void`                                                      |
+| getMediaList                     | 获取播放的媒资列表               | ^[Function]`() => Array<ESMediaItem> \| null`                                                      |
+| getMedia                         | 获取指定索引的媒资               | ^[Function]`(index: number) => ESMediaItem \| null`                                                      |
+| getPlayingMediaIndex             | 获取正在播放的媒资的索引          | ^[Function]`() => number`                                                      |
+| getPlayingMediaList              | 获取正在播放的媒资列表            | ^[Function]`() => ESMediaItemList \| null`                                                      |
+| getPlayingMedia                  | 获取正在播放的媒资               | ^[Function]`() => ESMediaItem \| null`                                                      |
+| getWindowType                    | 获取当前播放管理器的窗口类型       | ^[Function]`() => ESPlayerWindowType`                                                      |
+| setFloatWindow                   | 设置播放管理器浮动窗口            | ^[Function]`() => void`                                                      |
+| setSmallWindow                   | 设置播放管理器小窗口              | ^[Function]`() => void`                                                      |
+| setFullWindow                    | 设置播放管理器全屏窗口            | ^[Function]`() => void`                                                      |
+| setWindowType                    | 设置播放管理器窗口                | ^[Function]`(windowType: ESPlayerWindowType) => void`                                                      |
+| setPlayMediaListMode             | 设置播放媒资模式                 | ^[Function]`(playMode: ESPlayerPlayMode) => void`                                                      |
+| canPlayNextMedia                 | 判断是否可以播放视频列表下一个媒资   | ^[Function]`() => boolean`                                                      |
+| playNextMedia                    | 播放下一个媒资                   | ^[Function]`() => void`                                                      |
+| canPlayPreviousMedia             | 判断是否可以播放视频列表上一个媒资   | ^[Function]`() => boolean`                                                      |
+| playPreviousMedia                | 播放上一个媒资                   | ^[Function]`() => void`                                                      |
+| onKeyDown                        | 处理按键按下逻辑                 | ^[Function]`(keyEvent: ESKeyEvent) => boolean`                                                      |
+| onKeyUp                          | 处理按键抬起逻辑                 | ^[Function]`(keyEvent: ESKeyEvent) => boolean`                                                      |
+| onBackPressed                    | 处理返回键逻辑                   | ^[Function]`() => boolean`                                                      |

package/rules/.docs/zh-CN/component/player-manager/media-item-interceptor.md

@@ -0,0 +1,197 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# MediaItem 拦截器
+
+***`ESMediaItem`拦截器是`ESPlayerManager`调用`ESMediaItem`之前执行的钩子函数。***
+
+拦截器中，可以对`ESMediaItem`中所有的数据进行操作。
+
+***应用场景一：***
+
+播放`ESMediaItem`之前需要根据媒资分集 id 获取播放地址信息。
+
+设置数据`ESMediaItem`中的`mediaSourceList`暂时为空
+
+```ts
+const mediaItem: ESMediaItem = {
+  index: 0,
+  mediaSourceList: [],
+  interceptors: [interceptor]//添加异步获取播放地址拦截器
+}
+
+```
+
+可以通过拦截器异步请求到播放地址数据后，赋值给`ESMediaItem`中的`mediaSourceList`。
+
+***应用场景二：***
+
+播放媒资分集`ESMediaItem`之前需要判断用户是否有媒资分集`ESMediaItem`播放权益。
+
+```ts
+
+const mediaItem: ESMediaItem = {
+  index: 0,
+  mediaSourceList: [],
+  interceptors: [interceptor]//添加分集鉴权拦截器
+}
+```
+
+可以通过拦截器异步鉴权，并返回拦截结果，决定用户是否可以播放分集。
+
+## MediaItem 全局拦截器
+
+`ESMediaItem`全局拦截器可以在***整个应用中所有播放视频的位置***对`ESMediaItem`执行钩子函数操作。
+
+### 第一步、声明全局拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确保整个应用唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaItem`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaItem`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+export function createESPlayerMediaItemGlobalInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    //1.转换成 ESMediaItem
+    const item = params[0] as ESMediaItem
+    //2.模拟操作：给 ESMediaItem 添加数据
+    item.metadata = '全局拦截器添加的附加信息'
+    const mediaSource: ESMediaSource = {
+      uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/09/07/a2d3da6d-469e-4f99-a2d0-c001741003f8.mp4'
+    }
+    const mediaSourceList: ESMediaSourceList = {
+      index: 0,
+      list: [mediaSource]
+    }
+
+    //3.如果返回 Promise.resolve(result)  播放继续
+    // 则会把 ESPlayerInterceptResult中的 result 字段全部赋值到 ESMediaItem
+    // 如果返回 PPromise.reject('模拟失败') 播放终止，返回错误
+    //
+    const result: ESPlayerInterceptResult = {
+      result: {
+        mediaSourceList,
+        desc: '全局拦截器添加的附加字段'
+      }
+    }
+    return Promise.resolve(result)
+    // return Promise.reject('模拟失败')
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaItemGlobalInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM,
+    intercept,
+    release
+  }
+}
+```
+
+#### 第二步、注册全局拦截器
+
+```ts
+//1.创建全局拦截器
+const globalInterceptor = createESPlayerMediaItemGlobalInterceptor()
+//2.注册全局拦截器
+const globalInterceptorManager = useESPlayerInterceptorManager()
+globalInterceptorManager.addInterceptor(globalInterceptor)
+```
+
+## MediaItem 局部拦截器
+
+`ESMediaItem`局部拦截器可以在***此次播放中***对`ESMediaItem`执行钩子函数操作。
+
+### 第一步、声明局部拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确保整个应用唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaItem`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaItem`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+import {
+  ESPlayerInterceptorType
+} from "@extscreen/es3-player";
+import type {
+  ESIPlayerInterceptor, ESMediaSource, ESMediaSourceList,
+  ESPlayerInterceptResult
+} from "@extscreen/es3-player";
+import type { ESMediaItem } from "@extscreen/es3-player-manager";
+
+export function createESPlayerMediaItemGlobalInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    //1.
+    const item = params[0] as ESMediaItem
+    item.metadata = '全局拦截器添加的附加信息'
+
+    //2.
+    const mediaSource: ESMediaSource = {
+      uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/09/07/a2d3da6d-469e-4f99-a2d0-c001741003f8.mp4'
+    }
+    const mediaSourceList: ESMediaSourceList = {
+      index: 0,
+      list: [mediaSource]
+    }
+
+    const result: ESPlayerInterceptResult = {
+      result: {
+        mediaSourceList,
+        desc: '全局拦截器添加的附加字段'
+      }
+    }
+    return Promise.resolve(result)
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaItemGlobalInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM,
+    intercept,
+    release
+  }
+}
+
+
+```
+
+#### 第二步、注册局部拦截器
+
+```ts
+//1.创建局部拦截器
+const interceptor = createESPlayerMediaItemInterceptor()
+//2.注册局部拦截器
+const mediaItem: ESMediaItem = {
+  interceptors: [interceptor]
+}
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [mediaItem],
+}
+playerManager.value?.initialize()
+```
+
+:::demo ## 完整示例
+
+component/player-manager/media-item-interceptor
+
+:::

package/rules/.docs/zh-CN/component/player-manager/media-item-list-interceptor.md

@@ -0,0 +1,189 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# MediaItemList 拦截器
+
+***`MediaItemList`拦截器是`ESPlayerManager`调用`MediaItemList`之前执行的钩子函数。***
+
+拦截器中，可以对`ESMediaItemList`中所有的数据进行操作。
+
+***应用场景一：***
+
+播放媒资之前需要根据媒资 id 获取所有分集信息。
+
+设置数据`ESMediaItemList`中的`list`暂时为空
+
+```ts
+const playList: ESMediaItemList = {
+  id: '123456',
+  index: 0,
+  list: [],
+  interceptors: [interceptor],//添加异步获取分集拦截器
+}
+```
+
+可以通过拦截器异步请求到分集数据后，赋值给`ESMediaItemList`中的`list`。
+
+***应用场景二：***
+
+播放媒资之前需要判断用户是否有整个媒资的播放权益。
+
+```ts
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [mediaItem],
+  interceptors: [interceptor],//添加鉴权拦截器
+}
+```
+
+可以通过拦截器异步鉴权，并返回拦截结果，决定用户是否可以播放。
+
+## MediaItemList 全局拦截器
+
+`MediaItemList`全局拦截器可以在***整个应用中所有播放视频的位置***对`MediaItemList`执行钩子函数操作。
+
+### 第一步、声明全局拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确保整个应用唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM_LIST`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaItemList`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaSourceList`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+export function createESPlayerMediaItemListGlobalInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    //1.转换成 ESMediaItemList
+    const mediaItemList = params[0] as ESMediaItemList
+
+    //2.模拟操作：给 ESMediaItemList 添加数据
+    mediaItemList.metadata = '全局拦截器添加的附加信息'
+    const mediaSource: ESMediaSource = {
+      uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/09/07/a2d3da6d-469e-4f99-a2d0-c001741003f8.mp4'
+    }
+    const mediaSourceList: ESMediaSourceList = {
+      index: 0,
+      list: [mediaSource]
+    }
+    const mediaItem: ESMediaItem = {
+      mediaSourceList,
+    }
+
+    //3.如果返回 Promise.resolve(result)  播放继续
+    // 则会把 ESPlayerInterceptResult中的 result 字段全部赋值到 ESMediaSourceList
+    // 如果返回 PPromise.reject('模拟失败') 播放终止，返回错误
+    //
+    const result: ESPlayerInterceptResult = {
+      result: {
+        list: [mediaItem],
+        desc: '拦截器添加的新的字段'
+      }
+    }
+    return Promise.resolve(result)
+    // return Promise.reject('模拟失败')
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaItemListGlobalInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM_LIST,
+    intercept,
+    release
+  }
+}
+```
+
+#### 第二步、注册全局拦截器
+
+```ts
+//1.创建全局拦截器
+const globalInterceptor = createESPlayerMediaItemListGlobalInterceptor()
+//2.注册全局拦截器
+const globalInterceptorManager = useESPlayerInterceptorManager()
+globalInterceptorManager.addInterceptor(globalInterceptor)
+```
+
+## MediaItemList 局部拦截器
+
+`MediaItemList`局部拦截器可以在***此次播放中***对`MediaItemList`执行钩子函数操作。
+
+### 第一步、声明局部拦截器
+
+实现`ESIPlayerInterceptor`接口。
+
+* `id`需确此次播放中的唯一性。
+* ***`type`需明确指定为`ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM_LIST`***
+* ***`intercept`方法的参数`params`中`params[0]`即`ESMediaItemList`。 在次方法中进行业务逻辑，需要返回`promise`。
+  如果业务逻辑认为拦截成功则需返回`Promise.resolve(ESPlayerInterceptResult)`此时`ESPlayerInterceptResult`中的`result`字段会全部赋值到
+  `ESMediaSourceList`播放继续进行。 如果业务逻辑认为拦截失败则返回`Promise.reject()`播放返回错误，终止进行。***
+* `release`方法中有需回收资源
+
+```ts
+export function createESPlayerMediaItemListInterceptor(): ESIPlayerInterceptor {
+
+  function intercept(...params: Array<any>): Promise<ESPlayerInterceptResult> {
+    const mediaItemList = params[0] as ESMediaItemList
+    mediaItemList.metadata = '拦截器添加的附加信息'
+    const mediaSource: ESMediaSource = {
+      uri: 'http://qcloudcdn.a311.ottcn.com/data_center/videos/SHORT/DEFAULT/2023/08/25/7d3623ae-c002-4929-b5a2-fe10bca06bfc.mp4'
+    }
+    const mediaSourceList: ESMediaSourceList = {
+      index: 0,
+      list: [mediaSource]
+    }
+    const mediaItem: ESMediaItem = {
+      mediaSourceList,
+    }
+
+    const result: ESPlayerInterceptResult = {
+      result: {
+        list: [mediaItem],
+        desc: '拦截器添加的新的字段'
+      }
+    }
+    return Promise.resolve(result)
+    // return Promise.reject('模拟失败')
+  }
+
+  function release(): void {
+    //
+  }
+
+  return {
+    id: 'ESPlayerMediaItemListInterceptor',
+    type: ESPlayerInterceptorType.ES_PLAYER_INTERCEPTOR_TYPE_MEDIA_ITEM_LIST,
+    intercept,
+    release
+  }
+}
+
+```
+
+#### 第二步、注册局部拦截器
+
+```ts
+//1.创建局部拦截器
+const interceptor = createESPlayerMediaItemListInterceptor()
+//2.注册局部拦截器
+const playList: ESMediaItemList = {
+  index: 0,
+  list: [],
+  interceptors: [interceptor]
+}
+playerManager.value?.initialize()
+```
+
+:::demo ## 完整示例
+
+component/player-manager/media-item-list-interceptor
+
+:::

package/rules/.docs/zh-CN/component/player-manager/media-item-list.md

@@ -0,0 +1,31 @@
+---
+title: PlayerManager
+lang: zh-CN
+---
+
+# 操作播放列表
+
+某些业务场景下，播放列表可能需要异步获取，或者需要分页获取，这个时候就需要动态操作播放列表。
+
+## 操作播放列表
+
+* 向播放列表末尾添加数据：`addMediaToLast(mediaItemList: Array<ESMediaItem>): void;`
+* 向播放列表头部添加数据：`addMediaToFirst(mediaItemList: Array<ESMediaItem>): void;`
+* 向播放列表指定索引添加数据：`addMediaToIndex(index: number, mediaItemList: Array<ESMediaItem>): void;`
+* 替换播放列表中指定索引位置的数据：`replaceMedia(beginIndex: number, mediaItemList: Array<ESMediaItem>): void;`
+* 重置清空播放列表：`resetMediaList(): void;`
+
+## 获取正在播放媒资信息
+
+* 获取播放列表：`getMediaList(): SparseArray<ESMediaItem> | null;`
+* 获取正在播放的`ESMediaItem`的索引：`getPlayingMediaIndex(): number;`
+* 获取正在播放的`ESMediaItem`：`getPlayingMedia(): ESMediaItem | null;`
+* 获取正在播放的`ESMediaSourceList`：`getMediaSourceList(): Array<ESMediaSource> | null;`
+* 获取正在播放的`ESMediaSource`的索引：`getPlayingMediaSourceIndex(): number;`
+* 获取正在播放的`ESMediaSource`：`getPlayingMediaSource(): ESMediaSource | null;`
+
+:::demo ## 完整示例
+
+component/player-manager/media-item-list
+
+:::