弹幕本质是用绝对定位div模拟的动态DOM元素，非HTML原生支持；核心逻辑为监听视频时间、按时间戳拉取并创建弹幕元素、用CSS动画控制位移；需注意性能优化、移动端适配及时间精度控制。
弹幕本质是覆盖在视频上的动态 DOM 元素，不是 HTML 原生能力
HTML 本身不支持弹幕。所谓“HTML 视频弹幕”，实际是用 video 元素 + 绝对定位的 div 层模拟实现。浏览器不会解析 <track> 或 WebVTT 来渲染滚动文字——那些只用于字幕（subtitles），和弹幕（danmaku）在行为、格式、交互上完全不同。
核心逻辑就三点：监听视频播放时间 → 按时间戳拉取/触发对应弹幕 → 创建 span 或 div 插入到视频容器的绝对定位层中，并用 transform 或 left/top 控制位移动画。
常见错误现象：弹幕卡顿、重叠堆叠、不同步、点击穿透到视频控件、移动端错位。这些问题基本都出在定位策略或帧率同步上。
用 CSS 动画 + JavaScript 控制弹幕生命周期最轻量
不用框架、不引入 canvas，纯 DOM 方案适合中小项目。关键不是“怎么动”，而是“怎么管”：
立即学习“前端免费学习笔记（深入）”；
- 每条弹幕是一个
div，初始left: 100%，通过@keyframes动画从右向左平移，animation-duration根据屏幕宽度和期望速度动态计算 - 用
requestAnimationFrame替代setTimeout驱动时间轴，避免因 JS 阻塞导致弹幕批量延迟出现 - 必须限制同时显示的弹幕数（比如最多 15 条），超出则丢弃或合并，否则内存暴涨、回流严重；可用
document.querySelectorAll('.danmaku').length > 15实时判断 - 移动端需额外加
pointer-events: none到弹幕元素，否则会拦截video的点击全屏操作
示例关键 CSS：
@keyframes danmaku-fly {
from { transform: translateX(100vw); }
to { transform: translateX(-200px); }
}
.danmaku {
position: absolute;
top: 20%;
white-space: nowrap;
pointer-events: none;
animation: danmaku-fly 8s linear forwards;
animation-play-state: running;
}弹幕数据格式和加载时机决定体验上限
弹幕不是越快刷越好。真实场景下，用户拖拽进度、暂停、倍速都会打乱时间轴。所以不能只依赖“当前播放时间 === 弹幕时间戳”来触发，得预加载一段窗口（如 ±5 秒）内的弹幕并缓存。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
推荐结构（JSON 数组）：
[
{ "time": 12.34, "text": "前方高能", "color": "#ff6b6b", "mode": 1 },
{ "time": 13.01, "text": "已阅", "color": "#4ecdc4", "mode": 0 }
]mode 表示类型：0=滚动（默认）、1=顶部停留、2=底部停留、3=逆向滚动。很多库不支持 mode=1/2，结果所有弹幕挤在中间一行。
容易踩的坑：
- 直接用
fetch同步加载弹幕文件 → 视频已播到 30s，弹幕才开始加载 → 全部丢失。应提前在video的loadedmetadata事件后发起请求 - 服务端返回未按
time排序 → 前端要手动.sort((a,b) => a.time - b.time)，否则时间线错乱 - 没做防抖：同一毫秒内插入 20 条弹幕 → 页面瞬间卡死。建议用
requestIdleCallback批量插入，或限制最小间隔 50ms
第三方库选型要看清它真正解决的问题
用 bilibili-danmaku 或 moectf/danmaku 等库，不是为了“省事”，而是为了解决你没意识到的边界问题：比如 Web Worker 中解析大弹幕文件避免主线程阻塞、自动降帧适配低性能设备、兼容 iOS video 全屏时的 layer 重定位、处理 webkit-playsinline 下的定位偏移。
但也要警惕“过度封装”：
- 有些库强制要求你把弹幕写成 XML 格式 → 实际项目里后端几乎都返回 JSON，徒增转换成本
- 有些库把弹幕 DOM 挂在
body下 → 和你的视频容器不在同一transform上下文，缩放/旋转时位置飞掉 - 几乎所有库默认关闭弹幕碰撞检测 → 导致文字大面积重叠，尤其在 1080p 屏幕上，需要自己补
getBoundingClientRect()重叠判断逻辑
真正复杂的是时间精度控制和多端一致性，而不是“怎么让字跑起来”。大部分 demo 跑得通，上线一压测就飘，根源往往在 video.currentTime 的误差累积和 RAF 帧率抖动没被兜住。
