字
字节笔记本
2026年2月22日
flutter_annual_task：Flutter 年度任务网格组件
flutter_annual_task 是一个 Flutter 开源包，用于在应用中展示类似 GitHub 贡献图（GitHub Contributions Calendar）的年度任务网格视图。该组件可以直观地展示用户每日的任务完成情况，支持自定义颜色、形状和标签，非常适合用于习惯追踪、学习记录等场景。
项目简介
flutter_annual_task 由 HuanSuh 开发，是一个轻量级的 Flutter 组件库。它提供了一个 AnnualTaskView 小部件，可以将一年的 365 天以网格形式展示，每个单元格的颜色深浅代表当天的任务完成进度。截至目前，该包在 pub.dev 上获得了 45 个赞和 60 分，每周约有 37 次下载。
核心特性
- GitHub 风格贡献图：类似 GitHub 个人主页的贡献日历视觉效果
- 多种单元格形状：支持圆角方形（默认）、方形和圆形三种形状
- 自定义颜色：支持为每个单元格指定不同的颜色
- 进度展示：通过透明度展示任务完成进度（0.0 ~ 1.0）
- 灵活标签：可自定义星期和月份的标签文字
- 样式定制：支持自定义标签的文字样式
安装指南
在 pubspec.yaml 文件中添加依赖：
yaml
dependencies:
flutter_annual_task: ^0.2.0然后运行：
bash
flutter pub get在 Dart 文件中导入：
dart
import 'package:flutter_annual_task/flutter_annual_task.dart';快速开始
基础用法
dart
AnnualTaskView(
taskItems, // List<AnnualTaskItem>
)AnnualTaskItem 数据模型
dart
class AnnualTaskItem {
final DateTime date;
final double proceeding; // 0.0 ~ 1.0
AnnualTaskItem(this.date, [this.proceeding = 1.0]);
}proceeding 值影响单元格的透明度，用于展示任务完成程度。最小显示值为 80（最大 255）。
带颜色的任务项
如果需要为每个任务指定不同颜色，可以使用 AnnualTaskColorItem：
dart
class AnnualTaskColorItem extends AnnualTaskItem {
final Color color;
AnnualTaskColorItem(
DateTime date, {
double proceeding = 1.0,
this.color,
}) : super(date, proceeding);
}生成数据列表示例
dart
// 基础任务项
final taskItems = yourDataList.map(
(item) => AnnualTaskItem(
item.date,
0.5, // 完成进度
),
).toList();
// 带颜色的任务项
final coloredTaskItems = yourDataList.map(
(item) => AnnualTaskColorItem(
item.date,
color: item.color, // 为每个项指定颜色
),
).toList();使用示例
单元格形状
支持三种形状：圆角方形（默认）、方形和圆形。
方形：
dart
AnnualTaskView(
taskItems,
cellShape: AnnualTaskCellShape.SQUARE,
)圆形：
dart
AnnualTaskView(
taskItems,
cellShape: AnnualTaskCellShape.CIRCLE,
)标签配置
可以控制是否显示星期和月份标签：
dart
AnnualTaskView(
taskItems,
showMonthLabel: false, // 默认: true
showWeekDayLabel: false, // 默认: true
)自定义标签文字
dart
AnnualTaskView(
taskItems,
weekDayLabels: ['', 'Mon', '', 'Wed', '', 'Fri', ''],
monthLabels: ['1','2','3','4','5','6','7','8','9','10','11','12'],
)注意事项：
weekDayLabels从周日开始，长度必须为 7monthLabels长度必须为 12- 可以使用空字符串
''隐藏特定标签
自定义标签样式
dart
AnnualTaskView(
taskItems,
labelStyle: TextStyle(
color: Colors.blueGrey,
fontSize: 10,
fontWeight: FontWeight.bold,
),
)属性参考
| 属性 | 类型 | 说明 |
|---|---|---|
| items | List<AnnualTaskItem> | 任务数据列表 |
| year | int | 年份，默认：当前年份 |
| activateColor | Color | 激活颜色，默认：主题主色 |
| emptyColor | Color | 空单元格颜色，默认：Color(0xFFD0D0D0) |
| showWeekDayLabel | bool | 是否显示星期标签，默认：true |
| showMonthLabel | bool | 是否显示月份标签，默认：true |
| cellShape | AnnualTaskCellShape | 单元格形状，默认：ROUNDED_SQUARE |
| weekDayLabels | List<String> | 星期标签，默认：['S','M','T','W','T','F','S'] |
| monthLabels | List<String> | 月份标签，默认：['Jan','Feb',...,'Dec'] |
| labelStyle | TextStyle | 标签样式，默认：TextStyle(fontSize: 8) |
适用场景
- 习惯追踪应用：展示用户每日习惯打卡记录
- 学习记录：可视化学习进度和连续性
- 健身追踪：展示每日运动完成情况
- 代码贡献统计：类似 GitHub 的代码提交热力图
- 任务管理：年度任务完成度概览
项目链接
- Pub.dev: https://pub.dev/packages/flutter_annual_task
- GitHub 仓库: https://github.com/HuanSuh/flutter_annual_task
- 问题反馈: https://github.com/HuanSuh/flutter_annual_task/issues
- API 文档: https://pub.dev/documentation/flutter_annual_task/latest/
许可证
BSD-2-Clause License
分享: