mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-29 02:51:20 -08:00
docs(site): [SITE-04] document chapter and ambilight contracts in both languages
This commit is contained in:
Harvey Zhao committed
1 parent
dba354f8cd
commit
3138812610
86 files changed
+3857
-1748
No files matched your search
@@ -0,0 +1,88 @@
|
||||
# 视频背光
|
||||
|
||||
[English](../en/plugin/ambilight.md)
|
||||
|
||||
从视频画面采样颜色，在播放器周围显示模糊背光。插件使用 Canvas 读取像素，不需要额外 SDK，也不改变视频的播放或音频输出。
|
||||
|
||||
本页描述当前重构分支。生命周期修复及精确类型入口尚未发布；在线示例和未固定版本的 npm/CDN 包不等于当前候选。
|
||||
|
||||
## 安装和示例
|
||||
|
||||
```sh
|
||||
yarn add artplayer artplayer-plugin-ambilight
|
||||
```
|
||||
|
||||
```js
|
||||
import Artplayer from 'artplayer';
|
||||
import artplayerPluginAmbilight from 'artplayer-plugin-ambilight';
|
||||
```
|
||||
|
||||
使用 script 时先加载 ArtPlayer，再加载 `dist/artplayer-plugin-ambilight.js`，全局名为 `artplayerPluginAmbilight`。下面保留[在线背光示例](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ambilight/index.js&example=ambilight)的原始代码；应用需要提供自己的容器和可访问的视频。
|
||||
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-ambilight/index.js">▶ Run Code</div>
|
||||
|
||||
```js
|
||||
// npm i artplayer-plugin-ambilight
|
||||
// import artplayerPluginAmbilight from 'artplayer-plugin-ambilight';
|
||||
|
||||
const art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: '/assets/sample/video.mp4',
|
||||
autoSize: true,
|
||||
plugins: [
|
||||
artplayerPluginAmbilight({
|
||||
blur: '50px',
|
||||
opacity: 1,
|
||||
frequency: 10,
|
||||
duration: 0.3,
|
||||
}),
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `blur` | `string` | `'50px'` | CSS 模糊半径 |
|
||||
| `opacity` | `number` | `0.5` | 背光网格透明度；示例显式设置为 `1` |
|
||||
| `frequency` | `number` | `10` | 每秒采样次数上限，建议使用正数；实际频率受播放和帧调度限制 |
|
||||
| `duration` | `number` | `0.3` | 背光颜色过渡时长，单位秒 |
|
||||
| `zIndex` | `number` | 实际固定为 `9` | 保留的历史参数，不改变实际层级 |
|
||||
|
||||
插件按 3×3 网格采样颜色。它只在播放器处于播放状态且采样间隔满足条件时更新颜色；`frequency` 不是视频帧率设置。遮罩、裁剪或父容器的 `overflow` 样式也可能影响背光可见范围。
|
||||
|
||||
## start 和 stop
|
||||
|
||||
结果的 `name` 固定为 `artplayerPluginAmbilight`。在构造选项中安装时，插件收到播放器 `ready` 后开始调度：
|
||||
|
||||
```js
|
||||
const light = art.plugins.artplayerPluginAmbilight;
|
||||
light.stop(); // Stop sampling and retain the last colors.
|
||||
light.start(); // Resume sampling while the player is playing.
|
||||
```
|
||||
|
||||
两个方法都同步返回 `undefined`，不会播放或暂停视频。`stop()` 保留最后一次颜色；`start()` 不是“立即采一帧”的 Promise。重复调用不会创建多条采样循环。如果在播放器已经触发 `ready` 后才调用 `art.plugins.add(...)` 安装插件，需要自行调用返回结果的 `start()`。
|
||||
|
||||
插件没有 `update` 方法或独立的 `destroy` 方法。销毁播放器会停止帧调度、移除网格和插件订阅、释放采样画布。销毁后保留的 `start/stop` 不再启动工作。
|
||||
|
||||
## 媒体访问和代理
|
||||
|
||||
视频必须能被浏览器解码并允许 Canvas 读取像素。跨域视频需要正确的媒体跨域配置和服务端 CORS 响应；仅能播放不代表允许取色。像素读取失败时跳过该次更新并保留现有颜色，后续可读取的来源仍可恢复，插件不会绕过浏览器的跨域限制。
|
||||
|
||||
Canvas proxy 使用它实际输出的画布尺寸取样。其他代理能否提供可绘制画面需要分别验证；不要把一个桌面组合通过解释为所有浏览器或代理都支持。颜色采样也不代表物理显示器背光控制。
|
||||
|
||||
## TypeScript 兼容入口
|
||||
|
||||
根入口和 `/legacy` 保留已发布 1.1.0 的工厂类型：参数对象必填，字段可选。使用这些类型时传入 `{}` 选择默认值。JavaScript 运行时仍接受省略参数。
|
||||
|
||||
需要准确的可选调用、CommonJS `.default` 自引用或 NodeNext ESM 默认调用类型时，使用同一实现的 `/runtime`：
|
||||
|
||||
```ts
|
||||
import ambilight from 'artplayer-plugin-ambilight/runtime';
|
||||
|
||||
const installLight = ambilight();
|
||||
const installDefaultLight = ambilight.default({ opacity: 0.5 });
|
||||
```
|
||||
|
||||
根声明可导入的类型包括 `Option`、`Result`、`Callable`、`Factory` 和 `RuntimeFactory`。1.0.0 的 `export =` 及必填配置字段与 1.1.0 不同；旧 `import = require` 代码可迁到 `/runtime`，读取可选字段时提供默认值。Node10 TypeScript 默认导入 `/runtime` 需要启用 `esModuleInterop`，不启用时可用 `import = require`。
|
||||
@@ -23,7 +23,7 @@ import artplayerPluginAudioTrack from 'artplayer-plugin-audio-track';
|
||||
|
||||
下面与[在线音轨示例](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-audio-track/index.js&example=audio.track)使用同一份代码。站点提供示例媒体和 `.artplayer-app` 容器；接入自己的应用时替换这些地址和容器。
|
||||
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-audio-track/index.js"></div>
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-audio-track/index.js">▶ Run Code</div>
|
||||
|
||||
```js
|
||||
// npm i artplayer-plugin-audio-track
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
# 视频章节
|
||||
|
||||
[English](../en/plugin/chapter.md)
|
||||
|
||||
将进度条划分为章节，悬停时显示标题，并保留播放器原有的进度拖动和缩略图。插件不解析媒体文件中的章节元数据；章节时间由应用提供。
|
||||
|
||||
本页描述当前重构分支。候选版本和修复尚未发布，在线示例与未固定版本的 npm/CDN 包不一定包含本页所述修复。
|
||||
|
||||
## 安装和示例
|
||||
|
||||
```sh
|
||||
yarn add artplayer artplayer-plugin-chapter
|
||||
```
|
||||
|
||||
```js
|
||||
import Artplayer from 'artplayer';
|
||||
import artplayerPluginChapter from 'artplayer-plugin-chapter';
|
||||
```
|
||||
|
||||
使用 script 时先加载 ArtPlayer，再加载 `dist/artplayer-plugin-chapter.js`；插件全局名为 `artplayerPluginChapter`。下面保留[在线章节示例](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-chapter/index.js&example=chapter)的原始代码。站点提供示例容器、视频和缩略图，接入应用时替换为自己的资源。
|
||||
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-chapter/index.js">▶ Run Code</div>
|
||||
|
||||
```js
|
||||
// npm i artplayer-plugin-chapter
|
||||
// import artplayerPluginChapter from 'artplayer-plugin-chapter';
|
||||
|
||||
const art = new Artplayer({
|
||||
container: '.artplayer-app',
|
||||
url: '/assets/sample/video.mp4',
|
||||
autoSize: true,
|
||||
fullscreen: true,
|
||||
fullscreenWeb: true,
|
||||
miniProgressBar: true,
|
||||
autoOrientation: true,
|
||||
thumbnails: {
|
||||
url: '/assets/sample/thumbnails.png',
|
||||
number: 60,
|
||||
column: 10,
|
||||
},
|
||||
plugins: [
|
||||
artplayerPluginChapter({
|
||||
chapters: [
|
||||
{ start: 0, end: 18, title: 'One more chance' },
|
||||
{ start: 18, end: 36, title: '谁でもいいはずなのに' },
|
||||
{ start: 36, end: 54, title: '夏の想い出がまわる' },
|
||||
{ start: 54, end: 72, title: 'こんなとこにあるはずもないのに' },
|
||||
{ start: 72, end: Infinity, title: '终わり' },
|
||||
],
|
||||
}),
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
## chapters
|
||||
|
||||
工厂参数可以省略，也可以传入 `{ chapters }`。每个章节包含：
|
||||
|
||||
| 字段 | 类型 | 含义 |
|
||||
| --- | --- | --- |
|
||||
| `start` | `number` | 开始时间，单位秒，必须是非负有限数 |
|
||||
| `end` | `number` | 结束时间，单位秒；允许 `Infinity` 表示当前视频结束 |
|
||||
| `title` | `string` | 悬停标题；空字符串保留没有标题的区间 |
|
||||
|
||||
区间必须满足 `start < end <= 视频时长`，相邻章节不能重叠。插件会按开始时间排序，补齐头尾及章节之间的空白区间。它会**直接修改传入的数组**，包括排序、插入空标题章节和把 `Infinity` 替换为当前时长；需要保留原始配置时，每次传入新的数组及章节对象。
|
||||
|
||||
只有媒体时长为正的有限数时才生成章节。缺省、空或非数组的章节输入会清空视图；TypeScript 参数仍只接受声明的数组类型。字段类型错误会抛出 `TypeError`，非法时间或重叠区间会抛出 `Error`。标题按文本显示，不解析 HTML；显示时去除首尾空白，原对象的 `title` 不变。
|
||||
|
||||
## update
|
||||
|
||||
插件返回结果的 `name` 固定为 `artplayerPluginChapter`。`update(option)` 同步替换章节并返回 `undefined`，参数对象必填；`update({})` 清空章节：
|
||||
|
||||
```js
|
||||
art.plugins.artplayerPluginChapter.update({
|
||||
chapters: [{ start: 0, end: Infinity, title: 'Introduction' }],
|
||||
});
|
||||
|
||||
// Clear all chapter segments and the hover title.
|
||||
art.plugins.artplayerPluginChapter.update({});
|
||||
```
|
||||
|
||||
更新先清除旧视图再校验新数据；无效更新抛错后不会保留旧章节。成功更新会同步触发原有 `setBar('loaded', ...)`，进度交互继续使用核心控制器。
|
||||
|
||||
初始配置只在首次 `video:loadedmetadata` 时应用。切换媒体不会自动计算新章节；在新媒体加载后，调用 `update` 并传入适合新时长的全新数据。不要复用已经把 `Infinity` 改成旧时长的对象。
|
||||
|
||||
## 生命周期与样式
|
||||
|
||||
销毁播放器会移除插件自己的监听器、章节节点、标题及 `artplayer-plugin-chapter` 类，包括 `art.destroy(false)` 保留播放器 HTML 的情况。销毁后保留的结果对象调用 `update` 不会重建视图；没有单独的插件 `destroy()` 方法。
|
||||
|
||||
原有 `.art-chapter`、`.art-chapter-title` 和章节 `data-start/end/duration/title` 钩子保留。长标题在进度条宽度内截断，完整文字仍保存在文本和数据属性中。样式表由页面共享，销毁一个实例不会移除它。
|
||||
|
||||
## TypeScript
|
||||
|
||||
根入口及 `/legacy` 使用同一公开 API，可以导入 `Chapters`、`Option` 和 `Result` 类型；本包不需要另外切换到 `/runtime`：
|
||||
|
||||
```ts
|
||||
import artplayerPluginChapter from 'artplayer-plugin-chapter';
|
||||
import type { Chapters } from 'artplayer-plugin-chapter';
|
||||
|
||||
const chapters: Chapters = [{ start: 0, end: Infinity, title: 'Introduction' }];
|
||||
const installChapters = artplayerPluginChapter({ chapters });
|
||||
```
|
||||
|
||||
章节、清晰度、缩略图和全屏的桌面组合有独立测试；这不代表全部移动设备已通过。当前 Windows WebKit 的清晰度切换测试仍存在浏览器读取停顿，不能据此承诺所有平台均无时序问题。
|
||||
@@ -23,7 +23,7 @@ import artplayerPluginVttThumbnail from 'artplayer-plugin-vtt-thumbnail';
|
||||
|
||||
下面与[在线缩略图示例](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-vtt-thumbnail/index.js&example=vtt.thumbnail)使用同一份代码。站点提供媒体和 `.artplayer-app` 容器，自己的应用需要替换对应地址。
|
||||
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-vtt-thumbnail/index.js"></div>
|
||||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-vtt-thumbnail/index.js">▶ Run Code</div>
|
||||
|
||||
```js
|
||||
// npm i artplayer-plugin-vtt-thumbnail
|
||||
|
||||
Reference in new issue
Block a user