mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-24 14:41:20 -08:00
docs(core): [SITE-04] document component lifecycle and selector contracts
This commit is contained in:
Harvey Zhao committed
1 parent
5910c3f179
commit
bb2fec8dd1
110 files changed
+4745
-2334
No files matched your search
@@ -7,11 +7,12 @@
|
||||
| `disable` | `Boolean` | 是否禁用组件 |
|
||||
| `name` | `String` | 组件唯一名称，用于标记类名 |
|
||||
| `index` | `Number` | 组件索引，用于显示的优先级 |
|
||||
| `html` | `String`, `Element` | 组件的 DOM 元素 |
|
||||
| `html` | `String`, `Element`, `Number` | 组件的 DOM 元素 |
|
||||
| `style` | `Object` | 组件样式对象 |
|
||||
| `click` | `Function` | 组件点击事件 |
|
||||
| `mounted` | `Function` | 组件挂载后触发 |
|
||||
| `tooltip` | `String` | 组件的提示文本 |
|
||||
| `beforeUnmount` | `Function` | 显式 remove/update 移除前的回调 |
|
||||
| `tooltip` | `String`, `Number` | 组件的提示文本 |
|
||||
|
||||
## 创建
|
||||
|
||||
@@ -125,4 +126,23 @@ art.on('ready', () => {
|
||||
})
|
||||
}, 3000);
|
||||
});
|
||||
```
|
||||
```
|
||||
|
||||
## 菜单管理与生命周期 {#contextmenu-contract}
|
||||
|
||||
配置、回调、返回值、名字冲突及更新/清理规则见[组件公共行为](./layers#component-contract)。父节点为 template.$contextmenu；管理器名称是 contextmenu，条目类名为 art-contextmenu 和 art-contextmenu-NAME。show/toggle 控制整个菜单，不是单项可用状态；点击自定义条目不会自动关闭菜单，可在回调中设置 art.contextmenu.show = false。
|
||||
|
||||
桌面初始化安装内置条目和配置条目，并处理右键、键盘、菜单外点击及播放器 blur。移动端不会自动执行这段初始化；直接 add 仍可注册条目，但这不等于已安装完整的桌面右键流程。不要通过重复初始化来刷新菜单，用 add/update/remove 管理条目。
|
||||
|
||||
## TypeScript 菜单示例
|
||||
|
||||
```ts
|
||||
import Artplayer from 'artplayer/runtime';
|
||||
|
||||
const art = new Artplayer({ container: '#player', url: '/video.mp4' });
|
||||
const menu: HTMLDivElement | undefined = art.contextmenu.add({
|
||||
name: 'custom-menu', html: 'Close menu',
|
||||
click() { this.contextmenu.show = false; },
|
||||
});
|
||||
if (menu) art.contextmenu.remove('custom-menu');
|
||||
```
|
||||
@@ -7,12 +7,13 @@
|
||||
| `disable` | `Boolean` | 是否禁用组件 |
|
||||
| `name` | `String` | 组件唯一名称，用于标记类名 |
|
||||
| `index` | `Number` | 组件索引，用于显示的优先级 |
|
||||
| `html` | `String`, `Element` | 组件的 DOM 元素 |
|
||||
| `html` | `String`, `Element`, `Number` | 组件的 DOM 元素 |
|
||||
| `style` | `Object` | 组件样式对象 |
|
||||
| `click` | `Function` | 组件点击事件 |
|
||||
| `mounted` | `Function` | 组件挂载后触发 |
|
||||
| `tooltip` | `String` | 组件的提示文本 |
|
||||
| `position` | `String` | `left` 和 `right` 控制控制器出现的左右位置 |
|
||||
| `beforeUnmount` | `Function` | 显式 remove/update 移除前的回调 |
|
||||
| `tooltip` | `String`, `Number` | 组件的提示文本 |
|
||||
| `position` | `String` | 必填：top、left 或 right |
|
||||
| `selector` | `Array` | 选择列表的对象数组 |
|
||||
| `onSelect` | `Function` | 选择列表的元素被点击时触发的函数 |
|
||||
|
||||
@@ -175,4 +176,33 @@ art.on('ready', () => {
|
||||
});
|
||||
}, 3000);
|
||||
});
|
||||
```
|
||||
```
|
||||
|
||||
## 管理器与选择器行为 {#control-contract}
|
||||
|
||||
通用配置、回调、浅合并更新和资源清理见[组件公共行为](./layers#component-contract)。position 必须是 top、left 或 right，分别使用 template.$progress、$controlsLeft、$controlsRight；缺失或其他值会抛错。$parent 是最近一次 add 选择的位置，不代表全部控制器的公共父节点。顶层容器名为 control，类名为 art-control/art-control-NAME；没有 center 配置值。
|
||||
|
||||
add/update 返回 undefined。通过 mounted、cache.get(name)?.$ref 或已知名字属性取得节点。setting、thumbnails 是内置条目的可选节点引用，并非设置面板/缩略图数据对象。init 用于安装内置和配置条目，不是可重复调用的重置入口；再次安装可能因重名而失败。isHover 记录鼠标与底部区域的关系；timer 是上次显示时的时间戳，不是定时器句柄。自动隐藏依赖播放 timeupdate、CONTROL_HIDE_TIME、设置面板/输入/鼠标/键盘焦点状态，不能把它当作精确定时器。
|
||||
|
||||
selector 只在 left/right 位置生成选择列表。每项的 html 是显示内容、value 是自定义字符串/数字、default 是选中标记；value 不会自动驱动媒体切换。初始按钮内容来自控件的 html，初始 default 只标记列表项，不自动替换按钮内容。列表项与后续按钮内容通过 innerHTML 写入：请用可信字符串；即使历史类型允许 HTMLElement，这里也不会像普通组件 html 那样移动该节点。
|
||||
|
||||
点击时先更新各项 default、按钮内容和高亮，再调用 onSelect(item, itemElement, event)，this 为播放器。返回值（含 Promise 结果）会成为按钮的新 innerHTML；undefined 也不会自动回退到原内容。应返回需要显示的文字或 HTML。异步回调只有当前选择且条目仍有效时才更新标签；移除/替换后的结果和较早选择的结果被忽略。错误会记录警告，已更新的选择不自动回退。
|
||||
|
||||
controls.check(item) 可使用已绑定条目更新选中状态；无参数不做任何操作，不能传入任意未绑定对象。每项会得到只读、不可枚举的 $control_option（原数组）、$control_item（列表节点）、$control_value（按钮值节点）访问器。同一个条目对象不能同时属于两个活动选择器；旧控件释放后可以复用。controls.selector 是依赖内部托管节点和清理数组的渲染方法，应用应使用 add/update 的 selector 配置。
|
||||
|
||||
## TypeScript 控制器示例
|
||||
|
||||
```ts
|
||||
import Artplayer from 'artplayer/runtime';
|
||||
import type { SelectorItem } from 'artplayer/runtime';
|
||||
|
||||
const art = new Artplayer({ container: '#player', url: '/video.mp4' });
|
||||
const items: SelectorItem[] = [{ html: 'One', value: 1, default: true }, { html: 'Two', value: 2 }];
|
||||
const result: undefined = art.controls.add({
|
||||
name: 'choices', position: 'right', html: 'Choose', selector: items,
|
||||
async onSelect(item) { return String(item.html); },
|
||||
});
|
||||
art.controls.check(items[1]);
|
||||
console.log(result, art.controls.cache.get('choices')?.$ref);
|
||||
art.controls.remove('choices');
|
||||
```
|
||||
@@ -7,11 +7,12 @@
|
||||
| `disable` | `Boolean` | 是否禁用组件 |
|
||||
| `name` | `String` | 组件唯一名称，用于标记类名 |
|
||||
| `index` | `Number` | 组件索引，用于显示的优先级 |
|
||||
| `html` | `String`, `Element` | 组件的 DOM 元素 |
|
||||
| `html` | `String`, `Element`, `Number` | 组件的 DOM 元素 |
|
||||
| `style` | `Object` | 组件样式对象 |
|
||||
| `click` | `Function` | 组件点击事件 |
|
||||
| `mounted` | `Function` | 组件挂载后触发 |
|
||||
| `tooltip` | `String` | 组件的提示文本 |
|
||||
| `beforeUnmount` | `Function` | 显式 remove/update 移除前的回调 |
|
||||
| `tooltip` | `String`, `Number` | 组件的提示文本 |
|
||||
|
||||
## 创建
|
||||
|
||||
@@ -144,4 +145,38 @@ art.on('ready', () => {
|
||||
});
|
||||
}, 3000);
|
||||
});
|
||||
```
|
||||
```
|
||||
|
||||
## 组件公共行为 {#component-contract}
|
||||
|
||||
本节适用于 layers、controls 和 contextmenu；设置面板有自己的接口。
|
||||
|
||||
- add 接收配置对象或同步工厂 (art) => option。工厂参数是播放器，不能依赖工厂的 this。disable 为真时不创建节点；它不是已有节点的禁用开关。配置会被保留并可能修改，例如假值 html（包括数字 0）被归一为空字符串。
|
||||
- name 在同一个组件管理器内唯一。重复 add 会抛错，remove 不存在的名字也会抛错；update 不存在的名字会转为 add。省略 name 时使用管理器名称和递增 id。显式 name 同时成为管理器上的节点属性，请避免与 add、cache、show 等已有成员重名。
|
||||
- index 按升序插入同一个父容器；相同 index 的新节点插在旧节点之前。0 与省略 index 都使用递增 id，而非强制排在最前。不同 controls 位置分别排序。
|
||||
- html 字符串作为 HTML 插入，请使用可信内容；HTMLElement 会移动而非克隆。非零数字可作为内容。style 是直接赋给节点的样式对象，tooltip 接受字符串或数字，假值不生成提示。
|
||||
- click 的 this 是播放器，参数是组件管理器与原生事件，不是单个节点；调用前会 preventDefault，但不会自动 stopPropagation。mounted 和 beforeUnmount 的 this 也是播放器，参数是该节点。普通组件回调返回值被忽略，不等待 Promise。
|
||||
- mounted 在节点插入并写入 cache/名字属性后同步调用。beforeUnmount 在显式 remove 或 update 移除旧节点前同步调用；它抛错时旧条目保留。播放器 destroy 会释放托管资源，但不会逐项调用此钩子。自行创建的订阅、定时器等应有独立、可重复调用的清理函数，同时接到组件钩子与播放器 destroy。
|
||||
- update 按 name 将新配置浅合并到原配置对象，再 remove/add；会替换 DOM、重新运行 mounted，旧节点引用随之失效。style 等嵌套对象不深合并。beforeUnmount 读到的是合并后的配置；更新中替换钩子时也会使用新钩子。它不是失败时回滚旧节点的事务。
|
||||
|
||||
layers.add/update 和 contextmenu.add/update 返回新 HTMLDivElement，禁用或播放器关闭时可能是 undefined；controls.add/update 保留历史的 undefined 返回值。add/remove/update 已绑定，可单独保存后调用；toggle 需要保留管理器接收者。
|
||||
|
||||
show 控制整个管理器的 CSS 状态，toggle 取反。每次 show 赋值都会发出 layer、control 或 contextmenu 事件，即使布尔状态相同；它不删除条目。管理器的 art 指向播放器，name 分别是 layer/control/contextmenu，$parent 指向当前添加的父节点，id 是自增计数。cache 是按名字索引的 Map，每项含 $ref、events 清理函数数组及原 option；只作观察，不要直接改动这些字段来替代生命周期方法。
|
||||
|
||||
业务层父节点为 template.$layer，生成类名为 art-layer 和 art-layer-NAME。根类型保留 Component/ComponentOption/Selector 的历史形状，并用 ComponentInput 重载补充数字内容；未发布重构的 artplayer/runtime 导出准确的 Component、Controls、`ComponentInput<Host>` 和回调/返回值类型。cache 条目形状由实例推导；内部声明中的 ComponentEntry 并非此入口的命名导出。
|
||||
|
||||
## TypeScript 组件示例
|
||||
|
||||
```ts
|
||||
import Artplayer from 'artplayer/runtime';
|
||||
|
||||
const art = new Artplayer({ container: '#player', url: '/video.mp4' });
|
||||
const element: HTMLDivElement | undefined = art.layers.add({
|
||||
name: 'counter', html: 1,
|
||||
click(manager, event) { console.log(this === art, manager.name, event.type); },
|
||||
});
|
||||
if (element) {
|
||||
art.layers.update({ name: 'counter', html: 2 });
|
||||
art.layers.remove('counter');
|
||||
}
|
||||
```
|
||||
Reference in new issue
Block a user