# study-play

**Repository Path**: consuy1382/study-play

## Basic Information

- **Project Name**: study-play
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# study-player

独立的学习视频播放器组件库（Vue 2）。核心能力：HLS/MP4 播放、防快进（未学完限制拖拽）、防作弊（切屏检测 / 暂停超时归零 / 随机确认弹窗）、进度上报与续播。



---

## 目录结构

```
study-player/
├── src/
│   ├── index.js              # 统一出口：install 插件 + 具名导出
│   ├── components/
│   │   ├── VideoPlayer.vue       # 播放内核（封装 mui-player + hls.js）
│   │   ├── StudyPlayerWrapper.vue# 业务壳：注入取流/上报/防作弊，串联内核与 antiCheat
│   │   ├── antiCheat.js          # 防作弊逻辑工厂 createAntiCheat()
│   │   ├── ProgressBar.vue       # 进度条（含防快进上限）
│   │   └── VolumeControl.vue     # 音量滑块
│   └── demo/                  # 本地调试演示页
│       ├── App.vue
│       └── main.js
├── index.html
├── vite.config.js            # 同时支持 dev(demo) 与 build(库)
└── package.json
```

| 文件 | 职责 | 外部依赖 |
|---|---|---|
| `VideoPlayer.vue` | 只接收可直接播放的 `src`，处理 HLS/MP4 解析、进度/缓冲/全屏 | `mui-player`、`hls.js` |
| `StudyPlayerWrapper.vue` | 通过 props 注入 `resolveSrc`(取流) / `onProgress`(上报) / `antiCheatConfig`(防作弊) / `alert`(弹窗) | 无 |
| `antiCheat.js` | 纯逻辑工厂，监听切屏/暂停/随机时间点触发确认弹窗 | 无 |
| `ProgressBar.vue` | 进度展示 + 拖拽；`seekable=false` 时拖拽上限被 `maxTime` 限制 | 无 |
| `VolumeControl.vue` | 音量 UI | 无 |
| `index.js` | `Vue.use(StudyPlayer)` 或按需 `import` | 无 |

---

## 依赖（peerDependencies）

| 依赖 | 版本 | 说明 |
|---|---|---|
| `vue` | `^2.6.0 \|\| ^2.7.0` | 框架本身 |
| `mui-player` | `^1.6.0` | 播放器内核（仅 `VideoPlayer.vue` 引用） |
| `hls.js` | `^1.1.5` | m3u8 流解析（Chrome 不原生支持 HLS） |

> **不依赖 element-ui**：组件只用 `alert` 这个 prop 函数（调用方注入，可返回 Promise）。Demo 用自实现的极简弹窗，不引入任何 UI 库。

构建链：`vite` + `@vitejs/plugin-vue2` + `sass`（`<style lang="scss">`）。

---

## 自己构建脚本

> ⚠️ 运行前先切到 Node 18：`nvm use 18.18.0`

```powershell
nvm use 18.18.0
npm install        # 安装 devDependencies（含 peerDeps，供 demo 运行）
npm run dev        # 启动 vite，本地调试 src/demo 演示页
npm run build      # vite build -- lib 模式，产出 dist/（UMD + ESM），vue/mui-player/hls.js 已 external
npm run preview    # 预览构建产物
```

> 注：库构建通过 `vite.config.js` 的 `rollupOptions.external` 把 `vue`/`mui-player`/`hls.js` 排除出包，运行时由使用方提供，避免重复打包。

---

## 本地调试（dev）

```powershell
npm run dev
```
打开 vite 提示的本地地址（默认 `http://localhost:5173`）。`src/demo/App.vue` 提供：
- 顶部输入视频地址（m3u8/mp4 直链）+ 防作弊开关面板；
- 右侧「事件日志」实时打印 进度/完成/播放/暂停/归零 等事件（替代后端上报）。

浏览器 DevTools → Sources 可给 `.vue` 直接打断点。

---

## 作为库使用（在被集成的 Vue2 项目中）

### 1. 安装
```powershell
npm install git+https://gitee.com/consuy1382/study-play.git#v0.1.0
# peerDependencies 需由使用方提供：
npm install vue@^2.7 mui-player@^1.6 hls.js@^1.1
```

### 2. 注册 / 引入
```js
// 方式 A：整包注册（注册 VideoPlayer/ProgressBar/VolumeControl/StudyPlayerWrapper 四个全局组件）
import StudyPlayer from 'study-player'
Vue.use(StudyPlayer)

// 方式 B：按需引入（推荐，只引业务壳）
import { StudyPlayerWrapper, createAntiCheat } from 'study-player'
```

### 3. 模板使用
```vue
<study-player-wrapper
  :resource="resource"
  :resolve-src="resolveSrc"
  :seekable="seekable"
  :initial-time="initialTime"
  :max-time="maxTimeSeen"
  :record-interval="30000"
  :anti-cheat-config="antiCheatConfig"
  :alert="alertFn"
  :on-progress="onProgress"
  :on-complete="onComplete"
  :height="350"
  @play-state-change="onPlayState"
/>
```

> 集成示例可参考 `src/demo/App.vue`：`resolveSrc` 返回可直接播放的地址；`alert` 返回关闭后 resolve 的 Promise（供防作弊插 awaited）；`onProgress`/`onComplete` 在此仅打印，实际项目里改为调用后端上报接口。

---

## API —— `StudyPlayerWrapper` Props

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `resource` | `Object` | `null` | 资源对象；`id`/`zxkcId` 作为 `resourceId`，`isOutLink`/`outLink`/`yswj` 用于外链取流 |
| `resolveSrc` | `Function(resource) => string \| Promise<string>` | **必填** | 返回可直接播放的地址（取流逻辑由外部负责） |
| `seekable` | `Boolean` | `false` | `true`=已完成/自由观看，放开拖拽与防作弊；`false`=限制快进、启用防作弊 |
| `initialTime` | `Number` | `0` | 续播起点（秒） |
| `maxTime` | `Number` | `0` | 外部已学进度（秒），切换资源时回填 |
| `recordInterval` | `Number` | `30000` | 进度上报心跳间隔（毫秒） |
| `height` | `Number` | `350` | 播放器高度（px） |
| `antiCheatConfig` | `Object \| Function` | `null` | 防作弊配置（见下），支持函数动态返回 |
| `alert` | `Function(msg) => Promise` | `null` | 弹窗实现（关闭后 resolve） |
| `isLocked` | `Boolean` | `false` | 锁定态（如开放窗未通过），锁定时不触发防作弊/不上报 |
| `onProgress` | `Function({resourceId, maxTime, duration})` | `null` | 进度上报回调 |
| `onComplete` | `Function(resourceId)` | `null` | 学习完成回调 |

### Events
| 事件 | 参数 | 说明 |
|---|---|---|
| `play-state-change` | `isPlay: Boolean` | 播放/暂停状态变化 |

### Slots
| Slot | 说明 |
|---|---|
| `out-link` | 外链资源的自定义展示（默认「去观看」按钮） |

---

## `antiCheatConfig` 配置结构
```js
{
  preventSwitchTab: true,                              // 切屏检测（visibilitychange + window blur）
  pauseTimeoutMin: 0,                                  // 暂停超时归零（分钟，0=不归零）
  confirmTimeoutMin: 0,                                // 确认弹窗超时归零（分钟，0=不归零）
  randomConfirm: {
    count: 0,                                          // 随机确认次数
    minDurationMin: 0,                                 // 触发随机确认的最小视频时长（分钟）
    content: '请确认您正在学习'                          // 随机确认弹窗文案
  },
  switchTabContent: '请勿切换页面'                       // 切屏提示文案
}
```

防作弊行为：
- 切屏 → 暂停 + 弹窗，关闭后继续；
- 暂停超过 `pauseTimeoutMin` → 进度归零（`onReset`）；
- 播放到随机时间点 → 弹窗确认，超时则归零；
- 外链资源 / 已学完 (`seekable=true`) / 锁定态下不触发任何防作弊。

---

## `VideoPlayer`（内核）Props（一般不直接用）

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `src` | `String` | `null` | 可直接播放的地址（m3u8/mp4），`null` 时不初始化 |
| `height` | `Number` | `350` | 高度 |
| `seekable` | `Boolean` | `true` | 是否允许自由拖拽（防快进开关） |
| `maxTime` | `Number` | `0` | 最远观看位置（`.sync`），据此拦截快进 |
| `initialTime` | `Number` | `0` | 续播起点 |
| `recordInterval` | `Number` | `30000` | 上报心跳间隔（毫秒） |
| `isOutLink` | `Boolean` | `false` | 外链资源：不内置播放器，走 `out-link` slot |
| `outLink` | `String` | `null` | 外链地址 |

Events：`record` / `play-state-change` / `duration-change` / `out-link-open`。

---