Heatmap 热力图
要展示几周或一年里每天发生了多少事时用 Heatmap,就像 GitHub 的贡献图:提交、消息、完成的任务、登录次数。它让人一眼看出“什么时候忙”;要看随时间变化的确切数字,请用 Table;要列出一件件具体事件,请用 Timeline。
Heatmap 每天画一个格子:每周一列,每个星期几一行,数值越大颜色越深。上方是月份,左侧是星期,右下角是“少 … 多”图例。悬停或聚焦某一天会弹出 Tooltip,显示日期和数值,这段文字也是这一天的无障碍名称;方向键可以在日期之间移动。日期按本地日历日处理:"2026-11-19" 在任何时区打开都是这一天。周数超出容器宽度时可以横向滚动,初始停在最近的一周;左侧的星期不跟着滚动。
#演示
#基础用法
data 每天一项 { timestamp, value },timestamp 可以是 Date、毫秒时间戳或 YYYY-MM-DD 字符串。范围从 data 里最早的一天到最晚的一天;没有数据的日子按 0 计。unit 是提示里数值后面的单位。
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#最近一年
startDate 和 endDate 设定范围。fillCalendarLeading 把开始日所在那一周里更早的几天也填上,和 GitHub 个人主页一样。
| 周一 |
|---|
| 周三 |
| 周五 |
| 11月 | 12月 | 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#颜色主题
colorTheme 用某个主题角色色混出各级颜色,所以会跟随浅色和深色模式。
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#自定义颜色和级别
activeColors 替换空白以上的各级颜色,从浅到深;颜色的个数就是级别数。颜色请取自主题别名,这样会跟随主题。默认按数值占最大值的比例分级;thresholds 改为指定每一级的最小值。
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#尺寸和间距
size 决定格子和文字的大小;xGap 和 yGap 设定列与列、行与行之间的距离。
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#标签和每周第一天
星期、月份和图例都可以单独开关。firstDayOfWeek 决定第一行是星期几,0 是星期日。
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#提示和点击
renderTooltip 自定义某一天的提示内容,tooltip 接收 Tooltip 的 props,比如 placement(或传 false 关闭)。点击某一天,或在聚焦的那一天按 Enter、空格时会调用 onCellClick。
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#底部
footer 放在底部左侧。indicatorLeadingText 和 indicatorTrailingText 替换“少”和“多”;indicator 替换整个图例。
| 周一 |
|---|
| 周三 |
| 周五 |
| 1月 | 2月 | 3月 | 4月 | 5月 | 6月 | 7月 | 8月 | 9月 | 10月 | 11月 | 12月 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#加载中
loading 显示闪烁的占位格子:没有 data 时是一整年,有 data 时按 data 的形状。
| 周一 |
|---|
| 周三 |
| 周五 |
#Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
data | HeatmapDataItem[] | undefined | 每天一项 { timestamp, value }。同一天的值会相加;value: null 表示这一天没有数据 | 未发布 |
startDate | Date | number | string | undefined | 显示的第一天,默认是 data 里最早的一天 | 未发布 |
endDate | Date | number | string | undefined | 显示的最后一天,默认是 data 里最晚的一天;没有数据时显示截至今天的 52 周 | 未发布 |
fillCalendarLeading | boolean | false | 开始日所在那一周里更早的几天显示为空白日,而不是留空 | 未发布 |
firstDayOfWeek | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 0 | 第一行是星期几。0 是星期日,和 Date.getDay() 一致 | 未发布 |
colorTheme | primary | info | success | warning | error | accent | primary | 混出各级颜色的主题角色 | 未发布 |
activeColors | string[] | undefined | 空白以上各级的颜色,从浅到深,优先于 colorTheme | 未发布 |
minimumColor | string | undefined | 空白日的颜色 | 未发布 |
thresholds | number[] | undefined | 空白以上每一级的最小值,升序。不传时按数值占最大值的比例向上取整分级 | 未发布 |
size | small | medium | large | medium | 格子和文字的大小 | 未发布 |
xGap | number | string | undefined | 列间距,数字是 px,也可以是任意 CSS 长度。默认取尺寸对应的间距 | 未发布 |
yGap | number | string | undefined | 行间距,数字是 px,也可以是任意 CSS 长度。默认取尺寸对应的间距 | 未发布 |
showWeekLabels | boolean | true | 在左侧显示星期 | 未发布 |
showMonthLabels | boolean | true | 在上方显示月份 | 未发布 |
showColorIndicator | boolean | true | 在右下角显示图例 | 未发布 |
loading | boolean | false | 显示占位格子而不是数值 | 未发布 |
unit | string | undefined | 提示和无障碍名称里数值后面的单位 | 未发布 |
tooltip | boolean | HeatmapTooltipProps | true | 悬停和聚焦时的提示。false 关闭;传对象则作为 Tooltip 的 props | 未发布 |
renderTooltip | (cell: HeatmapCell) => ReactNode | undefined | 某一天的提示内容,默认是日期和数值 | 未发布 |
footer | ReactNode | undefined | 底部左侧的内容 | 未发布 |
indicator | ReactNode | undefined | 替换图例 | 未发布 |
indicatorLeadingText | ReactNode | undefined | 图例颜色前的文字,默认取语言包里的“少” | 未发布 |
indicatorTrailingText | ReactNode | undefined | 图例颜色后的文字,默认取语言包里的“多” | 未发布 |
onCellClick | (cell: HeatmapCell, event: MouseEvent | KeyboardEvent) => void | undefined | 点击某一天,或在某一天上按 Enter、空格时调用 | 未发布 |
aria-label 和 aria-labelledby 用来命名表格(默认是语言包里的“热力图”);其他 props 传给根 div。size、colorTheme 和 firstDayOfWeek 可以通过 ConfigProvider 的 componentOptions.Heatmap 统一设置。
HeatmapCell 是 { date, key, value, level, row, column }:date 是这一天的本地零点,key 是 YYYY-MM-DD 格式的日期,value 是当天合计(没有数据的日子是 0,标记为无数据的是 null),level 是颜色级别,0 表示空白。
月份、星期和提示里的日期由 Intl 按 ConfigProvider 的 locale 语言生成;图例文字和“无数据”来自语言包的 Heatmap 字段。