ckplayer-plus 1.1.2 → 1.1.4

package/README.md

@@ -1,176 +1,176 @@
-# ckplayer-plus
-
-基于 [ckplayer](https://www.ckplayer.com) X3 的工程化封装：支持 **npm / ESM**，并提供 **Vue 2.7+/3** 与 **React** 组件。
-
-> **免责声明**：本包为社区/工程化封装，**非 ckplayer 官方包**。播放内核来自 ckplayer（MIT）。完整能力与参数请同时参考 [官方手册](https://www.ckplayer.com/manual/)。npm 上的官方包名为 [`ckplayer`](https://www.npmjs.com/package/ckplayer)，请勿混淆。
-
-## 安装（只需这一步）
-
-```bash
-npm i ckplayer-plus
-```
-
-**不必再单独安装** `hls.js` / `flv.js` / `mpegts.js`。  
-包内已附带对应脚本；播放时会按视频地址**自动选择插件并按需加载**。
-
-## 自动识别规则（默认开启）
-
-| 地址特征 | 行为 |
-|----------|------|
-| `.mp4` 等浏览器可直接播的格式 | 原生 `<video>`，不加载流媒体脚本 |
-| `.m3u8` | 自动使用 `hls.js`（Safari 若原生支持则仍走原生） |
-| `.flv` | 自动使用 `flv.js` |
-| `.ts` / `.m2ts` / `.mts` | 自动使用 `mpegts.js` |
-
-关闭自动识别：`autoPlug: false`，并自行传 `plug`。
-
-## 引入样式（必做）
-
-```js
-import 'ckplayer-plus/style.css'
-```
-
-## 最简用法（mp4 / m3u8 都这样写）
-
-```js
-import ckplayer from 'ckplayer-plus'
-import 'ckplayer-plus/style.css'
-
-const player = new ckplayer({
-  container: '#player',
-  video: url // 可以是 mp4 或 m3u8，无需再写 plug
-})
-```
-
-Vue：
-
-```vue
-<CkPlayer :video="url" height="400px" />
-```
-
-React：
-
-```jsx
-<CkPlayer video={url} height="400px" />
-```
-
-## 配置说明（哪些要写、哪些不用写）
-
-### 常用且推荐
-
-| 配置 | 是否必须 | 默认 | 说明 |
-|------|----------|------|------|
-| `container` | 核心 API 必须；组件不用 | — | 播放器挂载节点。Vue/React 组件内部自动创建，**不要传** |
-| `video` | 必须 | — | 视频地址或清晰度数组 |
-| `poster` | 可选 | `''` | 封面图 |
-| `autoplay` | 可选 | `false` | 自动播放（移动端常需静音） |
-| `volume` | 可选 | `0.8` | 音量 0–1 |
-| `live` | 可选 | `false` | 直播相关 |
-| `width` / `height` | 组件可选 | `100%` / `400px` | 仅 Vue/React 组件样式 |
-
-### 一般不用写（已内置默认行为）
-
-| 配置 | 默认 | 说明 |
-|------|------|------|
-| `autoPlug` | `true` | 按地址自动选插件；通常保持默认即可 |
-| `plug` | 自动 | 仅在要强制指定或 `autoPlug: false` 时填写：`hls.js` / `flv.js` / `mpegts.js` |
-| `preferBuiltinPlug` | `true` | 优先加载本包内置脚本，避免复用页面上其它全局 `Hls` |
-| `cdnFallback` | `true` | `getPath` 失败时回退 jsDelivr；内网无外网请设 `false` 并配 `pluginPath` |
-| `pluginPath` | 自动 | 插件脚本根路径。默认：`window.ckplayerBasePath` → 本包 `dist/` → jsDelivr CDN |
-| `seek` | `0` | 续播秒数（number 或数字字符串）；会同步 `maxSeeTime`。HLS 优先用 `startPosition`，并等待缓冲后再跳，降低非关键帧解码失败 |
-| `loaded` | — | **只支持函数**；字符串形式已禁用（防 XSS） |
-
-### 进阶（按需）
-
-| 配置 | 说明 |
-|------|------|
-| `timeScheduleAdjust` | `5` 时只能在已看进度内拖动；续播请同时传数字 `seek` |
-| `crossOrigin` | 跨域视频 / 截图等场景 |
-| `cookie` | 进度记忆；组件默认使用实例唯一名，避免多实例冲突 |
-| `language` | 语言包名，如 `en`、`zh.hk`（需能加载到 `language/*.js`） |
-| `loop` / `controls` 等 | 与官方 ckplayer 一致，见[手册](https://www.ckplayer.com/manual/) |
-| `window.ckplayerBasePath` | 全局指定插件根目录（以 `/` 结尾），优先于 CDN |
-| `window.ckplayerPlusCdn` | 自定义 CDN 根地址（覆盖默认 jsDelivr） |
-
-### 插件加载优先级
-
-1. `preferBuiltinPlug: false` 且页面已有全局 `Hls` / `flvjs` / `mpegts` → 直接复用  
-2. 否则加载本包脚本：`pluginPath` 或可信的 `window.ckplayerBasePath`（仅 dist / npm 包路径会自动设置；Vite/Webpack chunk 目录会忽略）  
-3. 传统 `<script src=".../ckplayer.min.js">` 同级目录推导  
-4. `cdnFallback !== false` 时回退：`https://cdn.jsdelivr.net/npm/ckplayer-plus@x.y.z/dist/`；若本地路径 404 会再自动重试一次 CDN  
-
-> 内网离线：把 `node_modules/ckplayer-plus/dist/` 里的 `hls.js/` 等目录放到可访问静态路径，并设置 `pluginPath` 或 `window.ckplayerBasePath`，建议同时 `cdnFallback: false`。  
-> 样式请使用 `import 'ckplayer-plus/style.css'`，保证 `./images/` 图标能被打包工具解析。
-
-## Vue 2.7 / Vue 3
-
-支持 **Vue 2.7+** 与 **Vue 3**（需从 `vue` 解析 `h`，与 peerDependencies 一致）。
-
-```vue
-<template>
-  <CkPlayer :video="url" :seek="16" poster="/poster.png" height="400px" @play="onPlay" />
-</template>
-
-<script>
-import { CkPlayer } from 'ckplayer-plus/vue'
-import 'ckplayer-plus/style.css'
-
-export default {
-  components: { CkPlayer },
-  data() {
-    return { url: 'https://example.com/a.m3u8' } // 或 .mp4
-  },
-  methods: { onPlay() {} }
-}
-</script>
-```
-
-断点续播：`seek` 用 `:seek` 或 `options.seek` 在创建时传入；**不要**在 `@ready` 里再 `player.seek(16)`，否则会重复加载 HLS、取消 `.ts` 分片导致卡住。
-
-SSR（Nuxt 等）请用 `<ClientOnly>`，仅在浏览器初始化。
-
-## React
-
-```jsx
-import { CkPlayer } from 'ckplayer-plus/react'
-import 'ckplayer-plus/style.css'
-
-<CkPlayer video={url} height="400px" onPlay={() => {}} />
-```
-
-Next.js 使用 Client Component 或 `dynamic(..., { ssr: false })`。
-
-## 脚本标签
-
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ckplayer-plus/dist/ckplayer.css" />
-<script src="https://cdn.jsdelivr.net/npm/ckplayer-plus/dist/ckplayer.min.js"></script>
-<div id="player" style="width:800px;height:450px;"></div>
-<script>
-  new ckplayer({
-    container: '#player',
-    video: 'https://example.com/video.mp4'
-  })
-</script>
-```
-
-## 重要说明
-
-| 主题 | 说明 |
-|------|------|
-| SSR | 依赖 `document`，必须客户端初始化 |
-| 移动端自动播 | 常需 `volume: 0` 或用户手势 |
-| dash.js | 未实现 |
-| 体积 | 主包含流媒体 min 脚本以便「只装一个包」；运行时仍按需加载 |
-
-## 开发与发布
-
-```bash
-npm install
-npm run build
-npm publish --access public
-```
-
-## License
-
-MIT。内置的 hls.js / flv.js / mpegts.js 遵循各自许可证（多为 Apache-2.0）。
+# ckplayer-plus
+
+基于 [ckplayer](https://www.ckplayer.com) X3 的工程化封装：支持 **npm / ESM**，并提供 **Vue 2.7+/3** 与 **React** 组件。
+
+> **免责声明**：本包为社区/工程化封装，**非 ckplayer 官方包**。播放内核来自 ckplayer（MIT）。完整能力与参数请同时参考 [官方手册](https://www.ckplayer.com/manual/)。npm 上的官方包名为 [`ckplayer`](https://www.npmjs.com/package/ckplayer)，请勿混淆。
+
+## 安装（只需这一步）
+
+```bash
+npm i ckplayer-plus
+```
+
+**不必再单独安装** `hls.js` / `flv.js` / `mpegts.js`。  
+包内已附带对应脚本；播放时会按视频地址**自动选择插件并按需加载**。
+
+## 自动识别规则（默认开启）
+
+| 地址特征 | 行为 |
+|----------|------|
+| `.mp4` 等浏览器可直接播的格式 | 原生 `<video>`，不加载流媒体脚本 |
+| `.m3u8` | 自动使用 `hls.js`（Safari 若原生支持则仍走原生） |
+| `.flv` | 自动使用 `flv.js` |
+| `.ts` / `.m2ts` / `.mts` | 自动使用 `mpegts.js` |
+
+关闭自动识别：`autoPlug: false`，并自行传 `plug`。
+
+## 引入样式（必做）
+
+```js
+import 'ckplayer-plus/style.css'
+```
+
+## 最简用法（mp4 / m3u8 都这样写）
+
+```js
+import ckplayer from 'ckplayer-plus'
+import 'ckplayer-plus/style.css'
+
+const player = new ckplayer({
+  container: '#player',
+  video: url // 可以是 mp4 或 m3u8，无需再写 plug
+})
+```
+
+Vue：
+
+```vue
+<CkPlayer :video="url" height="400px" />
+```
+
+React：
+
+```jsx
+<CkPlayer video={url} height="400px" />
+```
+
+## 配置说明（哪些要写、哪些不用写）
+
+### 常用且推荐
+
+| 配置 | 是否必须 | 默认 | 说明 |
+|------|----------|------|------|
+| `container` | 核心 API 必须；组件不用 | — | 播放器挂载节点。Vue/React 组件内部自动创建，**不要传** |
+| `video` | 必须 | — | 视频地址或清晰度数组 |
+| `poster` | 可选 | `''` | 封面图 |
+| `autoplay` | 可选 | `false` | 自动播放。**课程/断点续播请保持 `false`**：有 `seek` 时组件会强制关闭自动播，只定位进度，需用户点击播放 |
+| `volume` | 可选 | `0.8` | 音量 0–1 |
+| `live` | 可选 | `false` | 直播相关 |
+| `width` / `height` | 组件可选 | `100%` / `400px` | 仅 Vue/React 组件样式 |
+
+### 一般不用写（已内置默认行为）
+
+| 配置 | 默认 | 说明 |
+|------|------|------|
+| `autoPlug` | `true` | 按地址自动选插件；通常保持默认即可 |
+| `plug` | 自动 | 仅在要强制指定或 `autoPlug: false` 时填写：`hls.js` / `flv.js` / `mpegts.js` |
+| `preferBuiltinPlug` | `true` | 优先加载本包内置脚本，避免复用页面上其它全局 `Hls` |
+| `cdnFallback` | `true` | `getPath` 失败时回退 jsDelivr；内网无外网请设 `false` 并配 `pluginPath` |
+| `pluginPath` | 自动 | 插件脚本根路径。默认：`window.ckplayerBasePath` → 本包 `dist/` → jsDelivr CDN |
+| `seek` | `0` | 续播秒数。HLS 对齐分片起点缓冲后再定位；**只 seek 不自动 play**，避免 Network 出现 canceled `.ts` |
+| `loaded` | — | **只支持函数**；字符串形式已禁用（防 XSS） |
+
+### 进阶（按需）
+
+| 配置 | 说明 |
+|------|------|
+| `timeScheduleAdjust` | `5` 时只能在已看进度内拖动；续播请同时传数字 `seek` |
+| `crossOrigin` | 跨域视频 / 截图等场景 |
+| `cookie` | 进度记忆；组件默认使用实例唯一名，避免多实例冲突 |
+| `language` | 语言包名，如 `en`、`zh.hk`（需能加载到 `language/*.js`） |
+| `loop` / `controls` 等 | 与官方 ckplayer 一致，见[手册](https://www.ckplayer.com/manual/) |
+| `window.ckplayerBasePath` | 全局指定插件根目录（以 `/` 结尾），优先于 CDN |
+| `window.ckplayerPlusCdn` | 自定义 CDN 根地址（覆盖默认 jsDelivr） |
+
+### 插件加载优先级
+
+1. `preferBuiltinPlug: false` 且页面已有全局 `Hls` / `flvjs` / `mpegts` → 直接复用  
+2. 否则加载本包脚本：`pluginPath` 或可信的 `window.ckplayerBasePath`（仅 dist / npm 包路径会自动设置；Vite/Webpack chunk 目录会忽略）  
+3. 传统 `<script src=".../ckplayer.min.js">` 同级目录推导  
+4. `cdnFallback !== false` 时回退：`https://cdn.jsdelivr.net/npm/ckplayer-plus@x.y.z/dist/`；若本地路径 404 会再自动重试一次 CDN  
+
+> 内网离线：把 `node_modules/ckplayer-plus/dist/` 里的 `hls.js/` 等目录放到可访问静态路径，并设置 `pluginPath` 或 `window.ckplayerBasePath`，建议同时 `cdnFallback: false`。  
+> 样式请使用 `import 'ckplayer-plus/style.css'`，保证 `./images/` 图标能被打包工具解析。
+
+## Vue 2.7 / Vue 3
+
+支持 **Vue 2.7+** 与 **Vue 3**（需从 `vue` 解析 `h`，与 peerDependencies 一致）。
+
+```vue
+<template>
+  <CkPlayer :video="url" :seek="16" poster="/poster.png" height="400px" @play="onPlay" />
+</template>
+
+<script>
+import { CkPlayer } from 'ckplayer-plus/vue'
+import 'ckplayer-plus/style.css'
+
+export default {
+  components: { CkPlayer },
+  data() {
+    return { url: 'https://example.com/a.m3u8' } // 或 .mp4
+  },
+  methods: { onPlay() {} }
+}
+</script>
+```
+
+断点续播：`seek` 用 `:seek` 或 `options.seek` 在创建时传入；**不要**在 `@ready` 里再 `player.seek(16)`，否则会重复加载 HLS、取消 `.ts` 分片导致卡住。有 `seek` 时不会自动播放，定位完成后点中央播放按钮即可。切集/切换清晰度同样不强制自动播。
+
+SSR（Nuxt 等）请用 `<ClientOnly>`，仅在浏览器初始化。
+
+## React
+
+```jsx
+import { CkPlayer } from 'ckplayer-plus/react'
+import 'ckplayer-plus/style.css'
+
+<CkPlayer video={url} height="400px" onPlay={() => {}} />
+```
+
+Next.js 使用 Client Component 或 `dynamic(..., { ssr: false })`。
+
+## 脚本标签
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ckplayer-plus/dist/ckplayer.css" />
+<script src="https://cdn.jsdelivr.net/npm/ckplayer-plus/dist/ckplayer.min.js"></script>
+<div id="player" style="width:800px;height:450px;"></div>
+<script>
+  new ckplayer({
+    container: '#player',
+    video: 'https://example.com/video.mp4'
+  })
+</script>
+```
+
+## 重要说明
+
+| 主题 | 说明 |
+|------|------|
+| SSR | 依赖 `document`，必须客户端初始化 |
+| 移动端自动播 | 常需 `volume: 0` 或用户手势 |
+| dash.js | 未实现 |
+| 体积 | 主包含流媒体 min 脚本以便「只装一个包」；运行时仍按需加载 |
+
+## 开发与发布
+
+```bash
+npm install
+npm run build
+npm publish --access public
+```
+
+## License
+
+MIT。内置的 hls.js / flv.js / mpegts.js 遵循各自许可证（多为 Apache-2.0）。