feiniao-youwei-uniapp/components/danmakuManager/README.md

弹幕组件使用说明

功能特性

• 固定高度200px的弹幕容器
• 支持无限滚动和单次滚动模式
• 多轨道智能分配，避免弹幕叠加
• 弹幕宽度根据文字长度自适应
• 支持用户头像显示（必显示）
• 自动清理已播放的弹幕
• 可自定义滚动速度
• 智能轨道占用管理

使用方法

基础用法

<template>
  <danmakuManager 
    :danmakuList="danmakuList" 
    :height="200" 
    :infinite="true"
    :speed="80"
    @danmakuComplete="onDanmakuComplete"
  ></danmakuManager>
</template>

<script setup>
import danmakuManager from "@/components/danmakuManager/danmakuManager.vue"

const danmakuList = ref([
  {
    text: "晨曦微露，阳光洒满大地",
    avatar: "头像URL"
  },
  {
    text: "守护果树，收获美好",
    avatar: null
  }
])

const onDanmakuComplete = (id) => {
  console.log('弹幕播放完成:', id)
}
</script>

Props 参数

参数	类型	默认值	说明
danmakuList	Array	[]	弹幕数据列表
height	Number	200	容器高度(px)
infinite	Boolean	true	是否无限循环
speed	Number	100	弹幕滚动速度(px/s)
trackCount	Number	8	弹幕轨道数量
spacing	Number	20	弹幕间距

弹幕数据格式

{
  text: "弹幕文本内容",
  avatar: "头像URL" // 必填，如果为null会使用默认头像
}

事件

事件名	参数	说明
danmakuComplete	id	弹幕播放完成时触发

方法

组件暴露了以下方法供父组件调用：

• addDanmaku(text, avatar) - 动态添加弹幕
• clearDanmakus() - 清空所有弹幕
• startDanmakuAnimation() - 开始弹幕动画
• stopDanmakuAnimation() - 停止弹幕动画

无限滚动 vs 单次滚动

<!-- 无限滚动 -->
<danmakuManager :infinite="true" :danmakuList="danmakuList"></danmakuManager>

<!-- 单次滚动 -->
<danmakuManager :infinite="false" :danmakuList="danmakuList"></danmakuManager>

样式定制

弹幕组件使用8个不同的轨道，每个轨道有不同的背景色：

• track-0: 红色
• track-1: 绿色
  
• track-2: 蓝色
• track-3: 黄色
• track-4: 紫色
• track-5: 青色
• track-6: 橙色
• track-7: 紫罗兰色

可以通过修改CSS来自定义轨道样式。

新增功能说明

1. 自适应宽度

• 弹幕宽度根据文字长度自动调整
• 使用 width: fit-content 实现自适应
• 设置最小宽度确保视觉效果

2. 必显示头像

• 每个弹幕都会显示用户头像
• 如果没有提供头像，会使用默认头像
• 头像大小固定为32rpx，圆形显示

3. 智能轨道管理

• 避免弹幕在同一轨道叠加
• 避免弹幕在相邻轨道叠加
• 智能分配可用轨道，确保轨道间距
• 记录轨道占用时间，自动释放
• 如果所有轨道都被占用，选择最早释放的轨道

4. 弹幕消失优化

• 确保弹幕完全离开可视范围才消失
• 增加额外的消失距离，避免弹幕突然消失
• 优化弹幕播放间隔，避免过于密集

5. 高度自适应优化

• 根据容器高度动态调整轨道间距
• 防止弹幕超出容器边界显示不完整
• 动态调整播放间隔，避免低高度容器中弹幕叠加
• 添加边界保护，确保弹幕完全显示

6. 弹幕稳定性优化

• 修复弹幕在滚动过程中高度掉下来的问题
• 确保弹幕在容器边界内完全显示
• 优化轨道分配算法，避免超出容器边界
• 固定弹幕元素高度，防止滚动时变形

7. 弹幕显示完整性优化

• 增加弹幕消失的缓冲距离，确保完全显示后再消失
• 优化弹幕宽度计算，更精确地估算文字宽度
• 增加内边距和文字间距，确保文字显示完整
• 延长弹幕动画时间，避免过早消失

8. 低高度容器优化

• 针对100px等低高度容器进行特殊优化
• 增加轨道间距，避免弹幕垂直叠加
• 减少可用轨道数量，确保弹幕有足够空间
• 增加播放间隔时间，避免弹幕过于密集
• 优化时间间隔计算，确保相邻弹幕不会叠加

9. 彻底解决叠加问题

• 采用严格轨道分配策略，只使用完全空闲的轨道
• 当没有空闲轨道时，暂停添加新弹幕
• 进一步减少低高度容器的可用轨道数量（最多2个）
• 大幅增加播放间隔时间，确保弹幕完全分离
• 避免任何形式的弹幕叠加，保证观看体验

10. 修复显示问题

• 优化轨道分配策略，确保弹幕能正常显示
• 采用三级轨道选择策略：完全空闲 > 任何空闲 > 最早释放
• 调整低高度容器的可用轨道数量为3个，平衡显示和防叠加
• 优化播放间隔时间，确保弹幕流畅显示
• 修复过于严格的轨道分配导致的弹幕不显示问题

11. 智能安全距离算法

• 实现基于时间的安全距离计算，确保弹幕不会前后叠加
• 采用安全性评分系统，优先选择最安全的轨道
• 低高度容器使用更长的安全时间间隔（3000ms）
• 智能轨道排序：完全安全 > 部分安全 > 等待
• 大幅增加播放间隔时间，确保弹幕完全分离
• 当没有安全轨道时，暂停添加新弹幕，避免强制叠加

12. 平衡显示与防叠加

• 回退到更平衡的轨道分配策略，确保弹幕能正常显示
• 采用三级轨道选择策略：完全空闲 > 任何空闲 > 最早释放
• 调整低高度容器的可用轨道数量为3个，平衡显示和防叠加
• 优化播放间隔时间，确保弹幕流畅显示且减少叠加
• 在保证弹幕正常显示的前提下，尽可能避免叠加

13. 页面生命周期管理

• 新增 autoStart 属性，控制弹幕是否自动开始播放
• 支持父组件手动控制弹幕的启动和停止
• 页面显示时自动启动弹幕，页面隐藏时自动停止弹幕
• 页面卸载时自动清理弹幕资源，避免内存泄漏
• 提供 startDanmakuAnimation() 和 stopDanmakuAnimation() 方法供外部调用

14. 超强防叠加算法

• 实现基于时间的安全距离计算，确保弹幕不会前后叠加
• 采用安全性评分系统，优先选择最安全的轨道
• 低高度容器使用更长的安全时间间隔（4000ms）
• 智能轨道排序：完全安全 > 部分安全 > 等待
• 大幅增加播放间隔时间（5000-9000ms），确保弹幕完全分离
• 当没有安全轨道时，暂停添加新弹幕，避免强制叠加
• 进一步减少低高度容器的可用轨道数量（最多2个）

15. 修复显示问题

• 回退到更平衡的轨道分配策略，确保弹幕能正常显示
• 采用三级轨道选择策略：完全空闲 > 任何空闲 > 最早释放
• 调整低高度容器的可用轨道数量为3个，平衡显示和防叠加
• 优化播放间隔时间（3000-5000ms），确保弹幕流畅显示且减少叠加
• 在保证弹幕正常显示的前提下，尽可能避免叠加
• 修复过于严格的轨道分配导致的弹幕不显示问题