leafer-canvas-player

v0.1.3

Published

22 days ago

A Leafer-based canvas video player component.

0High
0Medium
0Low

sjp199792

基于 leafer-editor 的 Canvas 视频播放器组件：用 <video> 作为“解码器 + 帧源”，每一帧绘制到 Leafer Canvas 上。这样视频就可以像普通 Leafer 节点一样被布局/缩放/裁切/叠加 UI。

特性

Leafer 节点化：VideoPlayer 继承自 Box，可直接加入你的 Leafer 场景树。
内置 UI：中心播放/暂停/加载态，底部进度条、时间、下载、全屏按钮。
可配置：封面图、缩放模式、进度条样式/布局、底部控制条整体开关。
TypeScript：导出 Config 类型与 d.ts。

安装

npm i leafer-canvas-player

本包依赖以下 peerDependencies（请在你的项目中自行安装）：

leafer-editor
@leafer-in/flow

快速开始

1) 创建播放器并加入 Leafer 场景树

VideoPlayer 是 Leafer 的 Box 子类，你可以把它 add 到任意容器（如 App 的根节点 / Group / Box）中。

import { VideoPlayer } from "leafer-canvas-player";

const player = new VideoPlayer({
  // 必填
  width: 640,
  height: 360,
  src: "https://example.com/video.mp4",

  // 可选
  poster: "https://example.com/poster.jpg",
  resizeMode: "contain",

  onPlay: () => console.log("play"),
  onPause: () => console.log("pause"),
  onTimeUpdate: (t) => console.log("time", t),
  onEnded: () => console.log("ended"),
  onFullScreen: () => {
    // 这里仅提供回调，你可以在外部实现全屏逻辑（例如把外层容器 requestFullscreen）
  }
});

// 伪代码：将 player 加入你的 Leafer 场景树（按你项目里实际的容器 API 来）
// app.tree.add(player) / group.add(player) / box.add(player) ...

Preview

2) 播放控制（可选）

player.play();
player.pause();

// 隐藏/显示底部控制条（进度条/时间/下载/全屏/底部播放暂停）
player.setControlsVisible(false);

3) 释放资源（推荐）

当你不再需要该实例时调用：

player.destroy();

支持项目

如果这个项目对你有帮助，欢迎在 GitHub 上点个 Star 支持一下，让我知道它值得继续维护与完善 🙂

API

导出

import { VideoPlayer } from "leafer-canvas-player";
import type { Config } from "leafer-canvas-player";

`new VideoPlayer(config: Config)`

Config = 业务参数 + Leafer Box 输入参数（IBoxInputData，但 width/height 由本组件强制要求传入）。

参数总览（字段级说明 + 默认值）

| 字段 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | width | number | 是 | - | 播放器宽度（像素） | | height | number | 是 | - | 播放器高度（像素） | | src | string | 是 | - | 视频 URL | | poster | string | 否 | - | 封面图 URL。传了会作为初始画面（Canvas fill image）；不传则会在 metadata 就绪后尝试渲染一帧作为封面。 | | resizeMode | "cover" \| "contain" | 否 | "contain" | 封面图（poster）的适配模式：cover=裁切铺满，contain=完整显示（letterbox）。 | | controlsVisible | boolean | 否 | true | 底部控制条总开关：关闭后会隐藏进度条 / 时间 / 下载 / 全屏 / 底部播放暂停（中心按钮仍由内部状态机控制）。 | | downloadVisible | boolean | 否 | true | “下载”按钮（右上角 Download HD）是否显示/可点击。注意：仍会受 controlsVisible=false 的总开关影响。 | | progressbarHeight | number | 否 | 10 | 兼容旧 API：进度条高度（仅在未提供 progressbar.height 时生效）。 | | progressbar | object | 否 | - | 进度条高级配置，见下表。 | | onPlay | () => void | 否 | - | 视频进入播放态时触发（video 的 play 事件）。 | | onPause | () => void | 否 | - | 视频进入暂停态时触发（video 的 pause 事件）。 | | onTimeUpdate | (currentTime: number) => void | 否 | - | 时间更新（秒）。注意：播放中也会触发；拖动/seek 时也会触发。 | | onEnded | () => void | 否 | - | 播放结束时触发。 | | onFullScreen | () => void | 否 | - | 点击“全屏”按钮触发（具体全屏行为由你在外部实现）。 | | fill | string \| object | 否 | "#000000" | 作为播放器容器 Box 的底色（不是视频内容）。不传时默认黑底。 | | cornerRadius | number \| number[] | 否 | 10 | 播放器容器圆角。 | | ...IBoxInputData | - | 否 | - | 其余参数会透传给 Box，常用的有 x/y/scale/rotation/opacity/visible/cursor/...（具体字段以 leafer-editor 的 IBoxInputData 为准）。 |

`progressbar` 详细参数（字段级说明 + 默认值）

说明：进度条的最终可见性/可交互性受三者共同控制：controlsVisible、progressbar.visible、progressbar.hittable。

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | left | number | 45 | 进度条左侧偏移 | | right | number | 50 | 进度条右侧偏移 | | bottomOffset | number | 40 | 未传 y 时，进度条距离底部的偏移 | | y | number | - | 进度条 y 绝对定位。传了会覆盖 bottomOffset 计算逻辑。 | | height | number | progressbarHeight（再默认 10） | 进度条高度 | | backgroundFill | string | rgba(255,255,255,0.2) | 轨道背景色 | | progressFill | string | rgba(255, 255, 255, 0.40) | 进度填充色 | | cornerRadius | number | 6 | 进度条圆角 | | backdropFilter | string | blur(6px) | 背景滤镜（需要运行环境/渲染层支持） | | visible | boolean | true | 是否显示进度条（仅进度条本身；不影响时间/下载/全屏） | | hittable | boolean | true | 是否允许点击跳转（tap-to-seek）。设为 false 可禁用交互。 |

参数示例（完整）

import { VideoPlayer } from "leafer-canvas-player";

const player = new VideoPlayer({
  width: 640,
  height: 360,
  src: "https://example.com/video.mp4",
  poster: "https://example.com/poster.jpg",
  resizeMode: "cover",

  // Box 参数（示例）
  x: 20,
  y: 20,
  cornerRadius: 12,
  fill: "#000",

  controlsVisible: true,
  progressbar: {
    left: 60,
    right: 60,
    bottomOffset: 24,
    height: 8,
    backgroundFill: "rgba(255,255,255,0.18)",
    progressFill: "rgba(255,255,255,0.55)",
    cornerRadius: 999,
    backdropFilter: "blur(8px)",
    visible: true,
    hittable: true
  }
});

实例方法

play(): void：播放（需要浏览器允许；通常要用户手势触发）
pause(): void：暂停
setControlsVisible(visible: boolean): void：显示/隐藏底部控制条
destroy(): void：释放资源（停止 RAF、解绑 video 事件、释放 <video>）

只读属性

duration: number：视频总时长（metadata ready 后才有值）

常见问题（非常重要）

自动播放策略

大多数浏览器限制自动播放：如果没有用户手势触发，play() 可能被拒绝或无效。建议让用户点击播放按钮后再调用 play()。

跨域（CORS）与 Canvas 绘制限制

本组件会把视频帧绘制到 Canvas 上。若视频是跨域资源，且服务端未配置正确的 CORS 头，浏览器可能：

无法绘制/出现黑屏；或
“污染 Canvas”（tainted），导致后续读取/导出等操作被禁止。

同时，内置“下载”按钮在多数情况下也要求视频资源支持 CORS（fetch(..., { mode: "cors" })）。

建议：

尽量使用同源资源；或
确保视频资源服务端开启 CORS（例如 Access-Control-Allow-Origin）。

SSR / Node

本组件依赖浏览器 DOM（例如 HTMLVideoElement / CanvasRenderingContext2D），不支持在 Node/SSR 环境直接运行。

如果你的项目有 SSR：

只在客户端渲染阶段创建 VideoPlayer
或使用动态导入（按你框架约定）

构建与发布（维护者）

本地开发

npm run dev

构建

npm run build

发布

发布前会自动执行（清理 + 构建）：

npm run prepublishOnly

发布流程（示例）：

npm version patch
npm publish

License

MIT

欢迎issues

欢迎提交 Issue（Bug/需求/文档改进都可以）。为了更快定位问题，建议在 Issue 中附上：

复现步骤（最好有最小可复现示例）
预期行为 vs 实际行为
运行环境（浏览器/版本、操作系统、leafer-editor 版本）
相关截图/录屏/报错堆栈