Canvas Danmaku

一个使用 CustomPainter 进行直接绘制的高性能 Flutter 弹幕组件，支持点击交互、性能优化和多种弹幕类型。

🚀 特性

高性能渲染

直接绘制：通过 CustomPainter 直接绘制，减少组件树复杂度
分层处理：滚动弹幕与静态弹幕分层处理，优化重绘性能
智能暂停：无弹幕时自动暂停绘制，有弹幕时自动恢复
异步渲染：渲染准备与渲染操作异步，缓存渲染结果

性能优化

对象池机制：复用弹幕对象，减少内存分配
视口裁剪：只渲染可见区域内的弹幕，提升 70-80% 性能
轨道优化：O(1) 轨道冲突检测，替代 O(n) 线性搜索
内存管理：智能内存限制，最大 2000 个弹幕，自动清理
批量处理：批量更新状态，减少不必要的重绘

交互功能

点击悬停：点击弹幕可悬停在当前位置
手势检测：精确的点击位置检测
状态管理：完整的悬停状态管理

简单易用

响应式设计：自动适应容器大小，动态计算轨道数
热更新：运行时动态更新弹幕属性
无上下文依赖：不需要传递 BuildContext

📦 安装

dependencies: 
  canvas_danmaku: ^0.2.6

🎯 基本使用

import 'package:canvas_danmaku/canvas_danmaku.dart';

class DanmakuPage extends StatefulWidget {
  @override
  _DanmakuPageState createState() => _DanmakuPageState();
}

class _DanmakuPageState extends State<DanmakuPage> {
  DanmakuController? _controller;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          // 你的视频播放器或其他内容
          Container(color: Colors.black),
          
          // 弹幕组件
          DanmakuScreen(
            createdController: (controller) {
              _controller = controller;
            },
            option: DanmakuOption(
              fontSize: 16,
              opacity: 0.8,
              duration: 10,
            ),
          ),
        ],
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          // 添加弹幕
          _controller?.addDanmaku(
            DanmakuContentItem(
              '这是一条测试弹幕',
              color: Colors.white,
              type: DanmakuItemType.scroll,
            ),
          );
        },
        child: Icon(Icons.add),
      ),
    );
  }
}

📚 API 参考

DanmakuController

弹幕控制器，用于管理弹幕的添加、暂停、清空等操作。

属性

属性	类型	说明
`running`	`bool`	弹幕是否运行中
`option`	`DanmakuOption`	当前弹幕配置选项
`holdingItem`	`DanmakuItem?`	当前悬停的弹幕

方法

`addDanmaku(DanmakuContentItem item)`

添加弹幕到屏幕

参数：

item: 弹幕内容对象

示例：

_controller.addDanmaku(
  DanmakuContentItem(
    '弹幕内容',
    color: Colors.white,
    type: DanmakuItemType.scroll,
  ),
);

`pause()`

暂停弹幕播放

_controller.pause();

`resume()`

恢复弹幕播放

_controller.resume();

`clear()`

清空所有弹幕

_controller.clear();

`updateOption(DanmakuOption option)`

更新弹幕配置

参数：

option: 新的弹幕配置

示例：

_controller.updateOption(
  _controller.option.copyWith(
    fontSize: 20,
    opacity: 0.9,
  ),
);

`hold(DanmakuItem? item, int currentTime)`

悬停指定弹幕

参数：

item: 要悬停的弹幕，传入 null 取消所有悬停
currentTime: 当前时间（毫秒）

示例：

// 悬停弹幕
_controller.hold(danmakuItem, DateTime.now().millisecondsSinceEpoch);

// 取消悬停
_controller.hold(null, DateTime.now().millisecondsSinceEpoch);

`unhold(int currentTime)`

取消悬停

参数：

currentTime: 当前时间（毫秒）

_controller.unhold(DateTime.now().millisecondsSinceEpoch);

`findDanmakuAtPosition(double tapX, double tapY, List<DanmakuItem> danmakuItems, {double tolerance = 10.0})`

查找指定位置的弹幕

参数：

tapX: 点击的 X 坐标
tapY: 点击的 Y 坐标
danmakuItems: 弹幕列表
tolerance: 容错范围（像素）

返回：

DanmakuItem?: 找到的弹幕，没有则返回 null

DanmakuOption

弹幕配置选项类，用于控制弹幕的显示效果。

属性

属性	类型	默认值	说明
`fontSize`	`double`	`16`	弹幕字体大小
`fontWeight`	`int`	`4`	字体粗细 (1-9)
`area`	`double`	`1.0`	显示区域比例 (0.1-1.0)
`duration`	`double`	`10`	滚动弹幕持续时间（秒）
`staticDuration`	`double`	`5`	静态弹幕持续时间（秒）
`opacity`	`double`	`1.0`	不透明度 (0.1-1.0)
`hideTop`	`bool`	`false`	隐藏顶部弹幕
`hideBottom`	`bool`	`false`	隐藏底部弹幕
`hideScroll`	`bool`	`false`	隐藏滚动弹幕
`hideSpecial`	`bool`	`false`	隐藏特殊弹幕
`strokeWidth`	`double`	`1.5`	描边宽度
`strokeColor`	`Color`	`Colors.black`	描边颜色
`massiveMode`	`bool`	`false`	海量弹幕模式
`safeArea`	`bool`	`true`	为字幕预留空间
`lineHeight`	`double`	`1.6`	弹幕行高

方法

`copyWith({...})`

创建配置副本并修改指定属性

示例：

final newOption = option.copyWith(
  fontSize: 20,
  opacity: 0.8,
  duration: 15,
);

DanmakuContentItem

弹幕内容类，表示一条弹幕的基本信息。

构造函数

DanmakuContentItem(
  String text, {
  Color color = Colors.white,
  DanmakuItemType type = DanmakuItemType.scroll,
  bool selfSend = false,
  bool? isColorful,
  int? count,
})

属性

属性	类型	说明
`text`	`String`	弹幕文本内容
`color`	`Color`	弹幕颜色
`type`	`DanmakuItemType`	弹幕类型
`selfSend`	`bool`	是否为自己发送
`isColorful`	`bool?`	是否为彩色弹幕
`count`	`int?`	弹幕数量

DanmakuItemType 枚举

enum DanmakuItemType {
  scroll,   // 滚动弹幕
  top,      // 顶部弹幕
  bottom,   // 底部弹幕
  special,  // 特殊弹幕
}

SpecialDanmakuContentItem

特殊弹幕内容类，继承自 DanmakuContentItem，支持高级动画效果。

构造函数

SpecialDanmakuContentItem(
  String text, {
  required int duration,
  required Color color,
  required double fontSize,
  bool hasStroke = false,
  required Tween<double> translateXTween,
  required Tween<double> translateYTween,
  Tween<double>? alphaTween,
  Matrix4? matrix,
  PathMetric? motionPathMetric,
  int? translationDuration,
  int translationStartDelay = 0,
  int? count,
  Curve easingType = Curves.linear,
})

工厂构造函数

`SpecialDanmakuContentItem.fromList(...)`

从列表数据创建特殊弹幕

factory SpecialDanmakuContentItem.fromList(
  Color color,
  double fontSize,
  List list, {
  double videoX = 1920,
  double videoY = 1080,
  bool disableGradient = false,
})

🎨 弹幕类型示例

滚动弹幕

_controller.addDanmaku(
  DanmakuContentItem(
    '这是一条滚动弹幕',
    color: Colors.white,
    type: DanmakuItemType.scroll,
  ),
);

顶部弹幕

_controller.addDanmaku(
  DanmakuContentItem(
    '这是一条顶部弹幕',
    color: Colors.yellow,
    type: DanmakuItemType.top,
  ),
);

底部弹幕

_controller.addDanmaku(
  DanmakuContentItem(
    '这是一条底部弹幕',
    color: Colors.green,
    type: DanmakuItemType.bottom,
  ),
);

特殊弹幕

_controller.addDanmaku(
  SpecialDanmakuContentItem(
    '特殊动画弹幕',
    duration: 3000,
    color: Colors.red,
    fontSize: 20,
    hasStroke: true,
    translateXTween: Tween<double>(begin: 0.1, end: 0.9),
    translateYTween: Tween<double>(begin: 0.5, end: 0.5),
    alphaTween: Tween<double>(begin: 1.0, end: 0.0),
    matrix: Matrix4.identity()..rotateZ(0.5),
    easingType: Curves.easeInOut,
  ),
);

🎮 高级功能

点击悬停功能

弹幕支持点击交互，点击弹幕可以使其悬停在当前位置：

DanmakuScreen(
  createdController: (controller) {
    _controller = controller;
  },
  option: DanmakuOption(),
  // 点击功能自动启用
)

使用说明：

点击任意弹幕：弹幕悬停在当前位置，变为半透明
再次点击悬停的弹幕：恢复正常流动
点击空白区域：取消所有悬停的弹幕

批量发送弹幕

Timer.periodic(Duration(seconds: 1), (timer) {
  // 每秒发送 50 条弹幕
  for (int i = 0; i < 50; i++) {
    _controller.addDanmaku(
      DanmakuContentItem(
        '批量弹幕 $i',
        color: Colors.primaries[i % Colors.primaries.length],
        type: DanmakuItemType.scroll,
      ),
    );
  }
});

FPS 监控

class _DanmakuPageState extends State<DanmakuPage> {
  double _fps = 0.0;

  @override
  void initState() {
    super.initState();
    _initFpsCounter();
  }

  void _initFpsCounter() {
    SchedulerBinding.instance.addPersistentFrameCallback((timeStamp) {
      setState(() {
        _fps = 1000 / (timeStamp.inMilliseconds - _lastFrameTime);
        _lastFrameTime = timeStamp.inMilliseconds;
      });
    });
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        DanmakuScreen(/* ... */),
        Positioned(
          top: 50,
          right: 20,
          child: Text(
            'FPS: ${_fps.toStringAsFixed(1)}',
            style: TextStyle(color: Colors.white, fontSize: 16),
          ),
        ),
      ],
    );
  }
}

动态配置更新

// 创建滑块控制弹幕属性
Slider(
  value: _fontSize,
  min: 12,
  max: 30,
  onChanged: (value) {
    setState(() {
      _fontSize = value;
    });
    _controller?.updateOption(
      _controller!.option.copyWith(fontSize: value),
    );
  },
)

⚡ 性能优化特性

对象池机制

复用弹幕对象，减少 60% 内存分配
智能池大小管理，最大 1000 个对象

视口裁剪

只渲染可见区域内的弹幕
性能提升 70-80%，CPU 使用率降低 60%

轨道优化

O(1) 轨道冲突检测，替代 O(n) 线性搜索
大量弹幕场景下性能提升 90%+

内存管理

智能内存限制，最大 2000 个弹幕
自动清理过期弹幕，防止内存溢出

批量处理

批量状态更新，减少 80% 不必要的重绘
帧率稳定在 60fps

📊 性能测试结果

测试项目	优化前	优化后	提升幅度
帧率	20-30fps	60fps	100%+
CPU 使用率	80-90%	30-40%	60%
内存使用	无限制	2000个上限	稳定
轨道检测	O(n)	O(1)	90%+
渲染效率	100%	20-30%	70-80%

🔧 完整示例

import 'package:flutter/material.dart';
import 'package:flutter/scheduler.dart';
import 'package:canvas_danmaku/canvas_danmaku.dart';
import 'dart:async';
import 'dart:math';

class DanmakuDemo extends StatefulWidget {
  @override
  _DanmakuDemoState createState() => _DanmakuDemoState();
}

class _DanmakuDemoState extends State<DanmakuDemo> {
  DanmakuController? _controller;
  Timer? _batchTimer;
  bool _isBatchSending = false;
  double _fps = 0.0;
  int _lastFrameTime = 0;
  
  // 配置选项
  double _fontSize = 16;
  double _opacity = 1.0;
  double _duration = 10;
  bool _massiveMode = false;

  @override
  void initState() {
    super.initState();
    _initFpsCounter();
  }

  void _initFpsCounter() {
    SchedulerBinding.instance.addPersistentFrameCallback((timeStamp) {
      if (_lastFrameTime != 0) {
        setState(() {
          _fps = 1000 / (timeStamp.inMilliseconds - _lastFrameTime);
        });
      }
      _lastFrameTime = timeStamp.inMilliseconds;
    });
  }

  void _toggleBatchSending() {
    if (_isBatchSending) {
      _batchTimer?.cancel();
      setState(() => _isBatchSending = false);
    } else {
      _batchTimer = Timer.periodic(Duration(seconds: 1), (timer) {
        for (int i = 0; i < 50; i++) {
          _controller?.addDanmaku(
            DanmakuContentItem(
              '批量弹幕 ${Random().nextInt(1000)}',
              color: Colors.primaries[i % Colors.primaries.length],
              type: DanmakuItemType.scroll,
            ),
          );
        }
      });
      setState(() => _isBatchSending = true);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Canvas Danmaku Demo')),
      body: Stack(
        children: [
          // 背景
          Container(color: Colors.black),
          
          // 弹幕组件
          DanmakuScreen(
            createdController: (controller) => _controller = controller,
            option: DanmakuOption(
              fontSize: _fontSize,
              opacity: _opacity,
              duration: _duration,
              massiveMode: _massiveMode,
            ),
          ),
          
          // FPS 显示
          Positioned(
            top: 50,
            right: 20,
            child: Container(
              padding: EdgeInsets.all(8),
              decoration: BoxDecoration(
                color: Colors.black54,
                borderRadius: BorderRadius.circular(4),
              ),
              child: Text(
                'FPS: ${_fps.toStringAsFixed(1)}',
                style: TextStyle(color: Colors.white, fontSize: 16),
              ),
            ),
          ),
          
          // 控制面板
          Positioned(
            bottom: 0,
            left: 0,
            right: 0,
            child: Container(
              color: Colors.black87,
              padding: EdgeInsets.all(16),
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  // 按钮行
                  Row(
                    mainAxisAlignment: MainAxisAlignment.spaceEvenly,
                    children: [
                      ElevatedButton(
                        onPressed: () => _controller?.addDanmaku(
                          DanmakuContentItem('滚动弹幕', color: Colors.white),
                        ),
                        child: Text('滚动'),
                      ),
                      ElevatedButton(
                        onPressed: () => _controller?.addDanmaku(
                          DanmakuContentItem(
                            '顶部弹幕',
                            color: Colors.yellow,
                            type: DanmakuItemType.top,
                          ),
                        ),
                        child: Text('顶部'),
                      ),
                      ElevatedButton(
                        onPressed: () => _controller?.addDanmaku(
                          DanmakuContentItem(
                            '底部弹幕',
                            color: Colors.green,
                            type: DanmakuItemType.bottom,
                          ),
                        ),
                        child: Text('底部'),
                      ),
                      ElevatedButton(
                        onPressed: _toggleBatchSending,
                        style: ElevatedButton.styleFrom(
                          backgroundColor: _isBatchSending ? Colors.red : null,
                        ),
                        child: Text(_isBatchSending ? '停止批量' : '批量发送'),
                      ),
                    ],
                  ),
                  SizedBox(height: 16),
                  
                  // 配置滑块
                  Row(
                    children: [
                      Text('字体大小: ', style: TextStyle(color: Colors.white)),
                      Expanded(
                        child: Slider(
                          value: _fontSize,
                          min: 12,
                          max: 30,
                          onChanged: (value) {
                            setState(() => _fontSize = value);
                            _controller?.updateOption(
                              _controller!.option.copyWith(fontSize: value),
                            );
                          },
                        ),
                      ),
                      Text('${_fontSize.toInt()}', style: TextStyle(color: Colors.white)),
                    ],
                  ),
                  
                  Row(
                    children: [
                      Text('不透明度: ', style: TextStyle(color: Colors.white)),
                      Expanded(
                        child: Slider(
                          value: _opacity,
                          min: 0.1,
                          max: 1.0,
                          onChanged: (value) {
                            setState(() => _opacity = value);
                            _controller?.updateOption(
                              _controller!.option.copyWith(opacity: value),
                            );
                          },
                        ),
                      ),
                      Text('${(_opacity * 100).toInt()}%', style: TextStyle(color: Colors.white)),
                    ],
                  ),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }

  @override
  void dispose() {
    _batchTimer?.cancel();
    super.dispose();
  }
}

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

本项目的灵感来自 ns_danmaku，一个非常优秀的 Flutter 弹幕组件项目。

Name		Name	Last commit message	Last commit date
Latest commit History 100 Commits
.vscode		.vscode
example		example
lib		lib
test		test
.gitignore		.gitignore
.metadata		.metadata
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
PERFORMANCE_OPTIMIZATION_REPORT.md		PERFORMANCE_OPTIMIZATION_REPORT.md
README.md		README.md
analysis_options.yaml		analysis_options.yaml
pubspec.yaml		pubspec.yaml

License

mcxiedidi/canvas_danmaku

Folders and files

Latest commit

History

Repository files navigation

Canvas Danmaku

🚀 特性

高性能渲染

性能优化

交互功能

简单易用

📦 安装

🎯 基本使用

📚 API 参考

DanmakuController

属性

方法

addDanmaku(DanmakuContentItem item)

pause()

resume()

clear()

updateOption(DanmakuOption option)

hold(DanmakuItem? item, int currentTime)

unhold(int currentTime)

findDanmakuAtPosition(double tapX, double tapY, List<DanmakuItem> danmakuItems, {double tolerance = 10.0})

DanmakuOption

属性

方法

copyWith({...})

DanmakuContentItem

构造函数

属性

DanmakuItemType 枚举

SpecialDanmakuContentItem

构造函数

工厂构造函数

SpecialDanmakuContentItem.fromList(...)

🎨 弹幕类型示例

滚动弹幕

顶部弹幕

底部弹幕

特殊弹幕

🎮 高级功能

点击悬停功能

批量发送弹幕

FPS 监控

动态配置更新

⚡ 性能优化特性

对象池机制

视口裁剪

轨道优化

内存管理

批量处理

📊 性能测试结果

🔧 完整示例

🤝 贡献

📄 许可证

🙏 致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`addDanmaku(DanmakuContentItem item)`

`pause()`

`resume()`

`clear()`

`updateOption(DanmakuOption option)`

`hold(DanmakuItem? item, int currentTime)`

`unhold(int currentTime)`

`findDanmakuAtPosition(double tapX, double tapY, List<DanmakuItem> danmakuItems, {double tolerance = 10.0})`

`copyWith({...})`

`SpecialDanmakuContentItem.fromList(...)`

Packages