react-activity-calendar从v2升级到v3:破坏性变更与全新Tooltip系统全解析
react-activity-calendar从v2升级到v3:破坏性变更与全新Tooltip系统全解析
react-activity-calendar 是一个用 React 展示活动数据热力图(GitHub 风格贡献日历)的开源组件库。v3 是一次重大版本更新:引入了纯 ESM 打包、内置 Tooltip 系统,同时带来了一批破坏性变更(Breaking Changes)。本文面向正在使用 v2 的开发者,带你逐条拆解从 v2 升级到 v3 需要改动的全部细节,帮助你在 10 分钟内完成无痛迁移。
v3 带来了什么
先看看升级后组件的实际渲染效果,这是一张完整年份的活动日历热力图,包含月份标签、活动总数统计和颜色图例:
v3 的核心亮点可以概括为三点:
- 📦 纯 ESM 包:整个包切换为纯 ES Module,对现代构建工具(Vite、Rollup 等)更友好,Tree-shaking 更高效
- 💬 全新内置 Tooltip 系统:不再依赖任何外部 Tooltip 库,通过代码拆分(Code Splitting)实现"用了才加载"
- 🧹 API 更简洁:移除了冗余 Props,命名风格从
hideXxx统一改为更直观的showXxx
升级前先看清单:破坏性变更速查表
📌 建议先通读下表,定位自己的项目受影响的部分,再深入对应章节:
| 变更类型 | v2 | v3 | 说明 |
|---|---|---|---|
| 打包格式 | CJS + ESM | 纯 ESM | 不支持 CommonJS 直接 require |
| 导出方式 | 默认导出 | 命名导出 | 默认导出被移除 |
| 事件处理 | eventHandlers prop |
renderBlock |
用 React.cloneElement 绑定事件 |
| 总数覆盖 | totalCount prop |
❌ 已移除 | 不再支持覆盖总数 |
| 隐藏颜色图例 | hideColorLegend |
showColorLegend |
改名,语义反转 |
| 隐藏月份标签 | hideMonthLabels |
showMonthLabels |
改名,语义反转 |
| 隐藏总数 | hideTotalCount |
showTotalCount |
改名,语义反转 |
| 加载骨架屏 | <Skeleton /> 组件 |
loading 状态 |
组件已移除 |
破坏性变更详解
1. 纯 ESM:构建工具需要注意什么
v3 现在是一个纯 ESM 包,入口定义见 package.json 的 exports 字段。对使用 Vite、Next.js、Astro 等现代框架的项目来说基本无感;但如果你还在用老式 Webpack 配置或直接 require 这个包,需要确认打包器支持 ESM。
💡 提示:Create React App 已停止维护且不受支持,官方建议使用 Vite 等项目脚手架。
2. 移除默认导出:改为命名导入
v2 里你可能这样写:
import ActivityCalendar from 'react-activity-calendar'
v3 中默认导出已被移除,必须使用命名导出(入口见 src/index.tsx):
import { ActivityCalendar } from 'react-activity-calendar'
这一步改动虽简单,却是升级时最容易踩的坑——忘记改导入方式会直接导致构建报错。
3. eventHandlers 被移除:用 renderBlock 重写事件
v2 的 eventHandlers prop 在 v3 中彻底移除。新的做法是通过 src/components/ActivityCalendar.tsx 中的 renderBlock 渲染 prop,配合 React.cloneElement 为每个日期方块(SVG rect 元素)附加事件:
import { cloneElement } from 'react'
<ActivityCalendar
data={data}
renderBlock={(block, activity) =>
cloneElement(block, {
onClick: () => console.log(activity),
})
}
/>
点击下方日历中的任意方块即可看到效果,完整示例代码参考 examples/event-handlers.tsx:
除了事件绑定,renderBlock 还能把方块包进链接里,灵活度比原来更高。
4. Props 改名:从 hide 到 show
三个控制显示/隐藏的 prop 全部改名为正向语义,且默认值都是 true(即默认显示),定义见 src/components/ActivityCalendar.tsx:
hideColorLegend→showColorLegendhideMonthLabels→showMonthLabelshideTotalCount→showTotalCount
注意语义是反转的:v2 中不传 hideMonthLabels 就显示月份,v3 中不传 showMonthLabels 也是显示——所以大多数项目只需删掉原来的 hide 写法,真正想隐藏时才传 showXxx={false}。
5. totalCount prop 被移除
v2 允许用 totalCount prop 覆盖底部显示的活动总数,v3 不再支持。总数现在完全由 data 中的 count 字段自动汇总(数据结构定义见 src/types.ts),想改文案可以通过 labels prop 里的 totalCount 模板(支持 {{count}} 和 {{year}} 占位符)来实现。
6. Skeleton 组件移除:加载状态新姿势
v2 的 <Skeleton /> 骨架屏组件已被移除。v3 的做法是给组件传 loading prop 并传入空数据,组件会渲染一套带加载动画的占位日历(内部逻辑见 src/hooks/useLoadingAnimation.ts):
<ActivityCalendar data={[]} loading />
效果如下图所示——数据未返回时展示柔和的占位方块,加载完成后平滑过渡到真实数据:
全新 Tooltip 系统深度解析
为什么重写:从外部依赖到内置
v3 的 Tooltip 不再依赖任何外部库,直接集成在包内部(实现见 src/components/Tooltip.tsx)。关键在于:
- 🪶 代码拆分:Tooltip 通过
React.lazy动态加载(见 src/components/ActivityCalendar.tsx#L46),只有你实际使用 tooltip 时,这部分代码才会进入你的 bundle - 🎯 基于 Floating UI:以"无头组件"(Headless)方式实现,自带位置计算、翻转避让、跟随滚动、无障碍 role 等能力,但不预设样式
- 🎨 样式完全可控:你可以引入官方默认样式,也可以完全自己写 CSS
如何启用 tooltips 配置
通过 tooltips prop 即可开启,分别配置日历方块(activity)和底部颜色图例(colorLegend)的提示文案,最小配置示例(完整示例见 examples/tooltips.tsx):
<ActivityCalendar
data={data}
tooltips={{
activity: {
text: ({ level, date }) => `${level} activities on ${date}`,
},
colorLegend: {
text: level => `Activity level ${level + 1}`,
},
}}
/>
除 text 文案函数外,每个 tooltip 还支持 TooltipConfig 中的高级选项:placement(弹出位置)、offset(偏移量)、transitionStyles(过渡动画)、hoverRestMs(悬停停留阈值)、withArrow(是否显示箭头)。
样式:默认 CSS 或自定义二选一
包内提供了官方默认样式,只需引入一行 CSS(打包后由 src/styles/tooltips.css 生成):
import 'react-activity-calendar/tooltips.css'
它已内置深色/浅色模式自动适配(通过 data-color-scheme 属性而非媒体查询判断,跟随组件自身的主题设置)。如果你有设计系统,也可以完全忽略这份默认样式,针对 .react-activity-calendar__tooltip 类名写自己的 CSS。
下面是升级 v3 后配合主题定制(theme prop)的完整渲染效果:
四步完成迁移:实操步骤
- ✅ 升级依赖:
npm install react-activity-calendar@latest,确认package.json中的版本已是 3.x - ✅ 改导入:把所有
import ActivityCalendar from ...改为import { ActivityCalendar } from ... - ✅ 替换 Props:按速查表把
hideXxx改为showXxx;删除eventHandlers与totalCount;把<Skeleton />换成data={[]} loading - ✅ 配置 Tooltip(可选):按需传入
tooltips配置,并引入react-activity-calendar/tooltips.css或自写样式
💡 官方完整的升级指南文档维护在 src/docs/ActivityCalendar.upgrading.mdx,升级时建议对照查阅。
值得深入阅读的源码与文档
- 主组件与全部 Props 定义:src/components/ActivityCalendar.tsx
- Tooltip 实现(Floating UI 集成):src/components/Tooltip.tsx
- 类型定义(Activity、Labels、Theme 等):src/types.ts
- 日历核心算法(分周、校验、空数据生成):src/lib/calendar.ts
- 主题颜色计算:src/lib/theme.ts
- 官方默认 Tooltip 样式:src/styles/tooltips.css
- 可运行的示例集(tooltip、事件、主题等):examples/
总结来说,v3 的破坏性变更虽然涉及导入方式、事件绑定和加载状态三处必改项,但整体方向是更现代(纯 ESM)、更轻量(Tooltip 按需加载)、更直观(show 系列命名)。跟着本文的速查表和四步迁移法,大多数项目只需改动几行代码就能平稳升级。



