القائمة
Guide for implementing real-time danmaku (bullet comments) player using Canvas. Invoke when building video players with danmaku support or debugging rendering/performance issues.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | danmaku-player |
| description | Guide for implementing real-time danmaku (bullet comments) player using Canvas. Invoke when building video players with danmaku support or debugging rendering/performance issues. |
基于 Canvas 的高性能弹幕播放器实现，参考 Bilibili 弹幕系统。包含完整的技术方案、性能优化和常见陷阱。
使用 Canvas 2D 渲染（推荐）
// ✅ 正确：Canvas 渲染，60fps 流畅
const canvas = canvasRef.current;
const ctx = canvas?.getContext('2d');
animationRef.current = requestAnimationFrame(renderDanmaku);
避免使用 DOM 渲染
// ❌ 错误：大量 DOM 节点导致卡顿
{danmakuList.map(d => <div key={d.id}>{d.text}</div>)}
原因：
interface DanmakuPlayerProps {
videoRef: React.RefObject<VideoPlayerRef | null>;
width: number;
height: number;
isPaused: boolean;
videoId: number;
episodeIndex: number;
}
// 关键 Refs
const danmakuListRef = useRef<DanmakuMessageDTO[]>([]); // 弹幕列表
const activeDanmakuRef = useRef<Array<{...}>>([]); // 活跃弹幕
const tracksRef = useRef<DanmakuTrack[]>([]); // 轨道管理
const animationRef = useRef<number | null>(null); // 动画帧
VideoPlayer 必须暴露 videoRef
export interface VideoPlayerRef {
getCurrentTime: () => number;
getVideoElement: () => HTMLVideoElement | null;
}
export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps>(
({ ... }, ref) => {
const videoRef = useRef<HTMLVideoElement>(null);
useImperativeHandle(ref, () => ({
getCurrentTime: () => videoRef.current?.currentTime || 0,
getVideoElement: () => videoRef.current,
}));
// ...
}
);
useEffect(() => {
const loadDanmaku = async () => {
try {
const response = await animeApi.getDanmakuList(videoId, episodeIndex);
if (response.success && response.data) {
danmakuListRef.current = response.data.danmakuList || [];
}
} catch (err) {
console.error('加载弹幕失败:', err);
}
};
loadDanmaku();
}, [videoId, episodeIndex]);
关键点：
const renderDanmaku = useCallback(() => {
const canvas = canvasRef.current;
const ctx = canvas?.getContext('2d');
const player = videoRef.current;
const video = player ? player.getVideoElement() : null;
if (!canvas || !ctx || !video) {
animationRef.current = requestAnimationFrame(renderDanmaku);
return;
}
const currentTime = video.currentTime;
// 1. 检测新弹幕（每 0.3 秒）
if (currentTime !== lastTimeRef.current && !isPaused) {
lastTimeRef.current = currentTime;
const newDanmaku = danmakuListRef.current.filter(d => {
if (Math.abs(d.timePosition - currentTime) >= 0.3) return false;
// 防止重复显示
const key = `${d.id}-${d.timePosition}`;
if (danmakuPoolRef.current.has(key as any)) return false;
return true;
});
// 2. 分配轨道
newDanmaku.forEach(d => {
let trackIndex = -1;
for (let i = 0; i < NUM_TRACKS; i++) {
const track = tracksRef.current[i];
if (!track || track.endTime < currentTime) {
trackIndex = i;
break;
}
}
if (trackIndex === -1) trackIndex = Math.floor(Math.random() * NUM_TRACKS);
const y = trackIndex * DANMAKU_HEIGHT + 10;
const x = width;
const speed = DANMAKU_SPEED * (0.8 + Math.random() * 0.4);
// 更新轨道占用时间
tracksRef.current[trackIndex] = {
y,
endTime: currentTime + (width + textWidth + DANMAKU_PADDING) / speed,
};
// 添加到活跃列表
activeDanmakuRef.current.push({
danmaku: d,
x,
y,
speed,
width: textWidth,
});
});
}
// 3. 清空画布
ctx.clearRect(0, 0, width, height);
// 4. 更新位置
activeDanmakuRef.current = activeDanmakuRef.current.filter(item => {
if (isPaused) return true;
item.x -= item.speed * 0.016; // 60fps 换算
return item.x > -item.width - DANMAKU_PADDING;
});
// 5. 绘制弹幕
activeDanmakuRef.current.forEach(item => {
const { danmaku, x, y } = item;
ctx.font = 'bold 22px "Microsoft YaHei", sans-serif';
ctx.fillStyle = danmaku.color || '#ffffff';
ctx.shadowColor = 'rgba(0, 0, 0, 0.8)';
ctx.shadowBlur = 4;
ctx.shadowOffsetX = 2;
ctx.shadowOffsetY = 2;
ctx.fillText(danmaku.content, x, y + 18);
ctx.shadowColor = 'transparent';
ctx.shadowBlur = 0;
ctx.shadowOffsetX = 0;
ctx.shadowOffsetY = 0;
});
animationRef.current = requestAnimationFrame(renderDanmaku);
}, [width, height, isPaused, videoRef]);
useEffect(() => {
animationRef.current = requestAnimationFrame(renderDanmaku);
return () => {
if (animationRef.current) {
cancelAnimationFrame(animationRef.current);
}
};
}, [renderDanmaku]);
interface DanmakuTrack {
y: number;
endTime: number; // 该轨道被占用到的时间
}
const NUM_TRACKS = 12; // 12 条轨道
const DANMAKU_HEIGHT = 30; // 每条弹幕高度
// 分配轨道算法
let trackIndex = -1;
for (let i = 0; i < NUM_TRACKS; i++) {
const track = tracksRef.current[i];
if (!track || track.endTime < currentTime) {
trackIndex = i; // 找到空闲轨道
break;
}
}
if (trackIndex === -1) {
trackIndex = Math.floor(Math.random() * NUM_TRACKS); // 全部占用则随机
}
const danmakuPoolRef = useRef<Map<number, DanmakuMessageDTO>>(new Map());
// 检测是否已显示
const key = `${d.id}-${d.timePosition}`;
if (danmakuPoolRef.current.has(key as any)) return false;
// 标记为已显示
danmakuPoolRef.current.set(`${d.id}-${d.timePosition}` as any, d);
❌ 错误：依赖变化导致循环
useEffect(() => {
const interval = setInterval(() => {
// 检查弹幕
}, 500);
return () => clearInterval(interval);
}, [videoRef, videoHeight]); // videoRef 每次渲染都变！
✅ 正确：使用 Ref 存储变化值
const videoHeightRef = useRef(videoHeight);
useEffect(() => {
videoHeightRef.current = videoHeight;
}, [videoHeight]);
useEffect(() => {
const interval = setInterval(() => {
const vh = videoHeightRef.current; // 使用 ref
// 检查弹幕
}, 500);
return () => clearInterval(interval);
}, [videoRef]); // 只依赖 videoRef
❌ 错误：弹幕加载阻塞视频
// 父组件加载弹幕
const { danmakuList, loadDanmaku } = useDanmakuList();
useEffect(() => {
loadDanmaku(videoId, episodeIndex); // 弹幕没加载完视频不播放
}, [videoId]);
✅ 正确：弹幕独立加载
// 弹幕层自己加载
useEffect(() => {
const loadDanmaku = async () => {
// 不影响视频
};
loadDanmaku();
}, [videoId, episodeIndex]);
❌ 错误：阻挡视频控制
<canvas style={{ pointerEvents: 'auto' }} /> // 拦截所有点击
✅ 正确：允许点击穿透
<div style={{ pointerEvents: 'none' }}>
<canvas style={{ pointerEvents: 'none' }} />
</div>
❌ 错误：频繁 setState
// 每帧更新状态
useEffect(() => {
const animate = () => {
setDanmakuList(prev => [...prev]); // 触发重渲染
animationRef.current = requestAnimationFrame(animate);
};
}, []);
✅ 正确：使用 Ref
// 数据存在 Ref，不触发重渲染
const activeDanmakuRef = useRef<Array<{...}>>([]);
const renderDanmaku = () => {
// 直接修改 Ref
activeDanmakuRef.current = filtered;
// Canvas 绘制，不依赖 React 状态
};
原因：
currentTime props，但父组件没传递解决：
// 弹幕层自己获取视频时间
const video = player ? player.getVideoElement() : null;
const currentTime = video.currentTime;
// 降级处理
if (trackIndex === -1) {
trackIndex = Math.floor(Math.random() * NUM_TRACKS);
}
原因：
解决：
// 1. 独立加载
useEffect(() => {
loadDanmaku(); // 异步不阻塞
}, []);
// 2. 使用 Ref，不 setState
const danmakuListRef = useRef([]);
// 3. 稳定依赖
const intervalRef = useRef<number | null>(null);
useEffect(() => {
if (intervalRef.current) clearInterval(intervalRef.current);
intervalRef.current = setInterval(checkDanmaku, 500);
return () => {
if (intervalRef.current) {
clearInterval(intervalRef.current);
intervalRef.current = null;
}
};
}, [videoRef]); // 只依赖 videoRef
原因：轨道管理失效
解决：
// 严格轨道占用检测
tracksRef.current[trackIndex] = {
y,
endTime: currentTime + (width + textWidth + DANMAKU_PADDING) / speed,
};
// 弹幕出屏后释放轨道
activeDanmakuRef.current = activeDanmakuRef.current.filter(item => {
if (item.x > -item.width - DANMAKU_PADDING) return true;
// 弹幕出屏，释放轨道（可选）
return false;
});
原因：canvas 的 pointerEvents: 'none' 导致无法捕获右键事件
解决：保留右键支持但允许其他点击穿透
const handleContextMenu = (e: MouseEvent) => {
e.preventDefault();
// 检测点击区域
const clickedDanmaku = activeDanmakuRef.current.find(item => {
return mouseX >= item.x && mouseX <= item.x + item.width;
});
if (clickedDanmaku) {
// 显示自定义菜单
setShowContextMenu(true);
}
};
canvas.addEventListener('contextmenu', handleContextMenu);
const NUM_TRACKS = 12; // 轨道数量
const DANMAKU_HEIGHT = 30; // 每条弹幕高度（px）
const DANMAKU_PADDING = 50; // 弹幕间距（px）
const DANMAKU_SPEED = 200; // 弹幕速度（px/s）
const CHECK_INTERVAL = 500; // 检查间隔（ms）
const TIME_THRESHOLD = 0.3; // 时间阈值（s）
// AnimeDetailPage.tsx
const videoPlayerRef = useRef<VideoPlayerRef>(null);
const [videoSize, setVideoSize] = useState({ width: 0, height: 0 });
const [isPaused, setIsPaused] = useState(false);
return (
<div className="relative">
<VideoPlayer
ref={videoPlayerRef}
src={videoSrc}
onSizeChange={(w, h) => setVideoSize({ width: w, height: h })}
onPauseChange={(paused) => setIsPaused(paused)}
/>
{videoSize.width > 0 && (
<DanmakuPlayer
videoRef={videoPlayerRef}
width={videoSize.width}
height={videoSize.height}
isPaused={isPaused}
videoId={videoId}
episodeIndex={episodeIndex}
/>
)}
<DanmakuInput
videoId={videoId}
episodeIndex={episodeIndex}
videoRef={videoPlayerRef}
/>
</div>
);
| 方案 | FPS | DOM 节点 | 内存占用 |
|---|---|---|---|
| Canvas（推荐） | 60 | 1 | 低 |
| DOM 方案 | 15-30 | N（弹幕数） | 高 |