react-activity-calendar从v2升级到v3:破坏性变更与全新Tooltip系统全解析

原创2026-11-18 16:46:191,418 阅读

react-activity-calendar从v2升级到v3:破坏性变更与全新Tooltip系统全解析

react-activity-calendar 是一个用 React 展示活动数据热力图(GitHub 风格贡献日历)的开源组件库。v3 是一次重大版本更新:引入了纯 ESM 打包、内置 Tooltip 系统,同时带来了一批破坏性变更(Breaking Changes)。本文面向正在使用 v2 的开发者,带你逐条拆解从 v2 升级到 v3 需要改动的全部细节,帮助你在 10 分钟内完成无痛迁移。

v3 带来了什么

先看看升级后组件的实际渲染效果,这是一张完整年份的活动日历热力图,包含月份标签、活动总数统计和颜色图例:

react-activity-calendar 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:

react-activity-calendar v3 renderBlock 事件处理器绑定效果示例

除了事件绑定,renderBlock 还能把方块包进链接里,灵活度比原来更高。

4. Props 改名:从 hide 到 show

三个控制显示/隐藏的 prop 全部改名为正向语义,且默认值都是 true(即默认显示),定义见 src/components/ActivityCalendar.tsx:

  • hideColorLegend → showColorLegend
  • hideMonthLabels → showMonthLabels
  • hideTotalCount → 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 />

效果如下图所示——数据未返回时展示柔和的占位方块,加载完成后平滑过渡到真实数据:

react-activity-calendar v3 内置 loading 加载状态替代 Skeleton 骨架屏

全新 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)的完整渲染效果:

react-activity-calendar v3 主题定制与日历热力图渲染效果

四步完成迁移:实操步骤

  1. ✅ 升级依赖:npm install react-activity-calendar@latest,确认 package.json 中的版本已是 3.x
  2. ✅ 改导入:把所有 import ActivityCalendar from ... 改为 import { ActivityCalendar } from ...
  3. ✅ 替换 Props:按速查表把 hideXxx 改为 showXxx;删除 eventHandlers 与 totalCount;把 <Skeleton /> 换成 data={[]} loading
  4. ✅ 配置 Tooltip(可选):按需传入 tooltips 配置,并引入 react-activity-calendar/tooltips.css 或自写样式

💡 官方完整的升级指南文档维护在 src/docs/ActivityCalendar.upgrading.mdx,升级时建议对照查阅。

值得深入阅读的源码与文档

总结来说,v3 的破坏性变更虽然涉及导入方式、事件绑定和加载状态三处必改项,但整体方向是更现代(纯 ESM)、更轻量(Tooltip 按需加载)、更直观(show 系列命名)。跟着本文的速查表和四步迁移法,大多数项目只需改动几行代码就能平稳升级。

登录后查看全文
react-activity-calendar