# SliderPlayer

**Repository Path**: wang-qingting/hmslider-player_2

## Basic Information

- **Project Name**: SliderPlayer
- **Description**: HarmonyOS流畅滑动解决方案
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 12
- **Created**: 2024-11-13
- **Last Updated**: 2024-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于SliderPlayer三方库的短视频流畅点播切换场景解决方案
## SliderPlayer简介
SliderPlayer三方库主要聚焦短视频流畅点播切换场景，提供短视频上下滑动切换和快速起播能力，同时通过自定义能力的开放满足应用不同短视频滑动场景的业务诉求。

SliderPlayer底层封装了系统AVPlayer及XComponent、Swiper、LazyForEach组件，基于AVPlayer的预创建，预加载以及提前起播实现了快速起播的能力。
SliderPlayer三方库通过对外提供一个SliderPlayer组件以及SliderPlayerController控制器对外提供能力，包括上下滑动、快速起播、动态添加数据源、
自定义跟随视频滑动的组件、自定义滑动组件切换、全屏和弹框等，目的是让开发者在开发过程中无需关注繁琐的AVPlayer创建、管理和播放逻辑，可以基于SliderPlayer
库能力快速实现短视频流畅滑动的场景开发体验，使开发者可以更加聚焦实际场景业务的开发。

## 特性
+ 支持网络视频（http/https）上下滑动及快速起播
+ 支持动态添加/刷新播放源数据
+ 支持自定义跟随视频滑动的组件
+ 支持自定义滑动组件切换
+ 支持自定义弹框（可自定义动画和弹框方向，提供默认动画实现）
+ 支持全屏/退出全屏播放，支持定义全屏播放界面组件
+ 支持进度条（通过组件形式提供）

## 依赖版本
HarmonyOS NEXT Beta1及以上
+ 手机版本：NEXT.0.0.26

## 下载安装
使用ohpm安装依赖
```shell
ohpm install @hadss/sliderplayer
```
或者按需在模块中配置运行时依赖，修改oh-package.json5
```json5
{
  "dependencies": {
    "@hadss/sliderplayer": "^1.0.0-rc.5"
  }
}
```

## 快速开始
### 支持网络视频（http/https）上下滑动及快速起播
定义控制器SliderPlayerController，初始化数据源，初始化SliderPlayer入口组件即可实现短视频滑动和快速起播能力。
```typescript
@Entry
@Component
struct Index {
  sources: Array<SliderPlayerDataSource> = new Array();
  sourceUrl: Array<string> = [
    'https://v-cdn.zjol.com.cn/276984.mp4',
    'https://v-cdn.zjol.com.cn/276985.mp4',
    'https://v-cdn.zjol.com.cn/276986.mp4'
  ]
}

// 1.定义控制器
sliderPlayerController: SliderPlayerController = new SliderPlayerController();

aboutToAppear(): void {
  // 2.创建播放源
  for (let sourceUrl of this.sourceUrls) {
    this.source.push(new SliderPlayerDataSource('video', sourceUrl)) 
  }
  
  onPageHide(): void {
    this.sliderPlayerController.pause();
  }

  onPageShow(): void {
    this.sliderPlayerController.pause();
  }
  
  build() {
    Column() {
      // 3.创建入口组件
      SliderPlayer({
        dataSource: new SliderPlayerIDateSource(this.source),
        sliderPlayerController: this.sliderPlayerController
      })
    }
    .height('100%')
    .width('100%')
  }
}
```

### 支持动态添加/刷新播放源数据
```typescript
@Entry
@Component
struct Index {
  sources: Array<SliderPlayerDataSource> = new Array();
  sourceUrl: Array<string> = [
    'https://v-cdn.zjol.com.cn/276984.mp4',
    'https://v-cdn.zjol.com.cn/276985.mp4',
    'https://v-cdn.zjol.com.cn/276986.mp4'
  ]
}

sliderPlayerController: SliderPlayerController = new SliderPlayerController();

aboutToAppear(): void {
  for (let sourceUrl of this.sourceUrls) {
    this.source.push(new SliderPlayerDataSource('video', sourceUrl)) 
  }
  
  onPageHide(): void {
    this.sliderPlayerController.pause();
  }

  onPageShow(): void {
    this.sliderPlayerController.pause();
  }
  
  build() {
    Column() {
      SliderPlayer({
        dataSource: new SliderPlayerIDateSource(this.source),
        sliderPlayerController: this.sliderPlayerController,
        options: {
          swiperCallback: {
            onAnimationStart: (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => {
              let totalNum = this.sliderPlayerController.getDataSourceSize();
              // 剩下最后5个数据时，动态添加数据源
              if (targetIndex - totalNum <= 5) {
                this.sliderPlayerController.addDataSources(new SliderPlayerDataSource('video',
                  'https://v-cdn.zjol.com.cn/276986.mp4'))
              }
              
              // 当前是第1个视频，且往下滑时，重新加载数据源
              if (index === 0 && targetIndex === 0) {
                this.sliderPlayerController.reloadDataSources(new Array(new SliderPlayerDataSource('video',
                  'https://v-cdn.zjol.com.cn/276991.mp4')))
              }
            }
          }
        }
      })
    }
    .height('100%')
    .width('100%')
  }
}
```

### 在滑动视频组件上添加自定义组件
短视频滑动场景往往包含很多随视频一起滑动的组件，如点赞评论转发，视频内容描述等，由于不同的应用这些自定义组件的内容各不相同，SliderPlayer提供自定义能力，
可以通过传递videoBuilder组件的形式定义这些随视频滑动的自定义组件。

### 自定义滑动切换组件（广告，图片轮播等）
短视频切换场景下除了视频播放场景外还可能存在广告页，图片轮播等场景和其他一些不可预期的页面，SliderPlayer提供自定义滑动切换组件的能力，
通过传递customBuilder组件的形式实现。

### 长按视频3s弹出倍速播放配置，选择倍速后弹出toast弹框提示并倍速播放视频
短视频滑动还涉及一些手势操作的业务场景，比如长按3s弹出配置页面，可以通过组件提供的Gesture手势事件注册能力实现，
使用SliderPlayerController提供的弹框能力可以弹出自定义配置页面，应用还可以通过AVPlayer创建回调注册AVPlayer回调监听speedDone事件并在回调中弹出toast提示。

### 点击评论按钮弹出评论页面，包含视频（缩放）上移动画，跟手动画
SliderPlayerController会封装点击页面弹框及视频动画并对外提供调用方法供应用使用，使用该方法时会弹出空白弹框，用户可以自定义弹框内容。
该弹框弹出式时会有默认视频动画（视频上移或缩放上移），收起弹框时默认有视频还原动画。

### 横向视频全屏播放
播放横向适配时，会额外显示全屏播放按钮，点击后全屏播放，并显示返回键，标题，进度条等内容，使用SliderPlayerController提供的全屏和退出全屏能力结合自定义组件videoBuilder实现。

### 实现自定义进度条
某些情况下应用不想使用默认进度条组件，需要实现自定义的进度条，可以通过options配置禁用显示默认进度条，然后通过videoBuilder结合AVPlayer监听事件注册实现自定义进度条。

## SliderPlayer接口和属性列表
### SliderPlayer: 短视频流畅点播切换入口组件
| 参数                                 | 说明                                                |
|------------------------------------|---------------------------------------------------|
| dataSource: SliderPlayerDataSource | 用于LazyForEach遍历的SliderPlayer的播放源数据对象              |
| controller: SliderPlayerController | SliderPlayer的控制器，提供全屏/退出全屏，弹框/关闭弹框及AVPlayer相关控制能力 |
| options: SliderPlayerOption        | SliderPlayer的参数配置，提供缓存数                           |

### SliderPlayerIDataSource: LazyForEach遍历的数据源对象
| 参数                                         | 说明                   |
|--------------------------------------------|----------------------|
| dateSources: Array<SliderPlayerDataSource> | SliderPlayer的播放源数据列表 |

| 接口原型       | 参数                                                          | 返回值                    | 接口描述              |
|------------|-------------------------------------------------------------|------------------------|-------------------|
| totalCount |                                                             | number                 | SliderPlayer播放源总数 |
| getData    | index: number                                               | SliderPlayerDataSource | 获取数据源对象           |
| pushData   | data: SliderPlayerDataSource; Array<SliderPlayerDataSource> | void                   | 动态添加数据源           |
| reloadData | data: Array<SliderPlayerDataSource>                         | void                   | 重新刷新数据源           |

### VideoSliderPlayerDataSource: 视频播放类型数据源对象（实现SliderPlayerDataSource）
| 参数                                  | 说明                                                                  |
|-------------------------------------|---------------------------------------------------------------------|
| type: 'video                        | 短视频播放源类型                                                            |
| sourcePath: string                  | 短视频播放源路径，支持http/https                                               |
| videoBuilder?: CustomBuilder        | 视频播放组件上的自定义组件（会跟随视频一起滑动）                                            |
| fullScreenBuilder?: CustomerBuilder | 全屏播放时，视频组件上的自定义组件                                                   |
| cover?: Resource                    | 视频封面，支持gif(在AVPlayer的initialize, prepared, playing期间显示，不设置默认显示黑屏画面) |
| pauseIcon?: Resource                | 用户点击视频暂停时显示的图标（默认为透明白色三角）                                           |

### CustomSliderPlayerDataSource: 自定义类型数据源对象（实现SliderPlayerDataSource）
| 参数                            | 说明                         |
|-------------------------------|----------------------------|
| type: 'custom'                | 自定义播放类型源                   |
| customBuilder?: CustomBuilder | 用户自定义的非视频类型的滑动组件（如广告，图片轮播） |

### CustomBuilder: 用户自定义组件对象
| 参数                                       | 说明            |
|------------------------------------------|---------------|
| customBuilder?: WrappedBuilder<[Object]> | 用户自定义组件       |
| dataObj?: object                         | 用户自定义组件匹配的数据源 |

### 配置参数: SliderPlayerOptions
| 参数                             | 说明                               |
|--------------------------------|----------------------------------|
| cachedCount                    | LazyForEach缓存数量，范围0-3，默认1        |
| swiperCallBack? SwiperCallback | SliderPlayer包装的Swiper组件的一些滑动回调注册 |

### SwiperCallback: Swiper回调注册
| 参数                                                                                               | 说明                            |
|--------------------------------------------------------------------------------------------------|-------------------------------|
| onAnimationStart?: (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => void | 对应Swiper组件的onAnimationStart回调 |
| onAnimationEnd?: (index: number, extraInfo: SwiperAnimationEvent) => void                        | 对应Swiper组件的onAnimationEnd回调   |
| onChange?: (index: number) => void                                                               | 对应Swiper组件的onChange回调         |

### SliderPlayerController: SliderPlayer组件的控制器
| 接口原型              | 参数                                                                                           | 返回值                  | 接口描述                        |
|-------------------|----------------------------------------------------------------------------------------------|----------------------|-----------------------------|
| getAVPlayer       |                                                                                              | media.AVPlayer       | 获取当前播放的AVPlayer对象，存在获取不到的情况 |
| async play        |                                                                                              | void                 | 播放当前视频，有状态校验                |
| async pause       |                                                                                              | void                 | 暂停播放当前视频，有状态校验              |
| seek              |                                                                                              | void                 | 跳转到指定位置播放，有状态校验             |
| requestFullScreen |                                                                                              | void                 | 请求全屏播放，会隐藏videoBuilder组件    |
| exitFullScreen    |                                                                                              | void                 | 退出全屏播放，会显示videoBuilder组件    |
| openDialog        | builder: DialogBuilder, directionOrAnimationCallback: PushDirection \| OpenAnimationCallback | void                 | 打开自定义弹框页面，支持设置弹框方向和自定义动画    |
| closeDialog       | builder: animation: CloseAnimationCallback                                                   | void                 | 关闭自定义页面弹框（可支持自定义动画）         |
| getXCustomBuilder |                                                                                              | xComponentId: string | 当前播放的XComponent组件id         |

### AVPlayerListener
| 接口原型    | 参数                                                 | 返回值  | 接口描述 |
|---------|----------------------------------------------------|------|------|
| onEvent | key: string, callback: (...args: ESObject) => void | void | 注册回调 |

## 开源协议
本项目基于 Apache License 2.0，请自由地享受和参与开源。