跳到正文

Heatmap 热力图

要展示几周或一年里每天发生了多少事时用 Heatmap,就像 GitHub 的贡献图:提交、消息、完成的任务、登录次数。它让人一眼看出“什么时候忙”;要看随时间变化的确切数字,请用 Table;要列出一件件具体事件,请用 Timeline。

Heatmap 每天画一个格子:每周一列,每个星期几一行,数值越大颜色越深。上方是月份,左侧是星期,右下角是“少 … 多”图例。悬停或聚焦某一天会弹出 Tooltip,显示日期和数值,这段文字也是这一天的无障碍名称;方向键可以在日期之间移动。日期按本地日历日处理:"2026-11-19" 在任何时区打开都是这一天。周数超出容器宽度时可以横向滚动,初始停在最近的一周;左侧的星期不跟着滚动。

演示

基础用法

data 每天一项 { timestamp, value },timestamp 可以是 Date、毫秒时间戳或 YYYY-MM-DD 字符串。范围从 data 里最早的一天到最晚的一天;没有数据的日子按 0 计。unit 是提示里数值后面的单位。

最近一年

startDate 和 endDate 设定范围。fillCalendarLeading 把开始日所在那一周里更早的几天也填上,和 GitHub 个人主页一样。

颜色主题

colorTheme 用某个主题角色色混出各级颜色,所以会跟随浅色和深色模式。

自定义颜色和级别

activeColors 替换空白以上的各级颜色,从浅到深;颜色的个数就是级别数。颜色请取自主题别名,这样会跟随主题。默认按数值占最大值的比例分级;thresholds 改为指定每一级的最小值。

尺寸和间距

size 决定格子和文字的大小;xGap 和 yGap 设定列与列、行与行之间的距离。

标签和每周第一天

星期、月份和图例都可以单独开关。firstDayOfWeek 决定第一行是星期几,0 是星期日。

提示和点击

renderTooltip 自定义某一天的提示内容,tooltip 接收 Tooltip 的 props,比如 placement(或传 false 关闭)。点击某一天,或在聚焦的那一天按 Enter、空格时会调用 onCellClick。

底部

footer 放在底部左侧。indicatorLeadingText 和 indicatorTrailingText 替换“少”和“多”;indicator 替换整个图例。

加载中

loading 显示闪烁的占位格子:没有 data 时是一整年,有 data 时按 data 的形状。

Props

名称类型默认值说明版本
dataHeatmapDataItem[]undefined每天一项 { timestamp, value }。同一天的值会相加;value: null 表示这一天没有数据未发布
startDateDate | number | stringundefined显示的第一天,默认是 data 里最早的一天未发布
endDateDate | number | stringundefined显示的最后一天,默认是 data 里最晚的一天;没有数据时显示截至今天的 52 周未发布
fillCalendarLeadingbooleanfalse开始日所在那一周里更早的几天显示为空白日,而不是留空未发布
firstDayOfWeek0 | 1 | 2 | 3 | 4 | 5 | 60第一行是星期几。0 是星期日,和 Date.getDay() 一致未发布
colorThemeprimary | info | success | warning | error | accentprimary混出各级颜色的主题角色未发布
activeColorsstring[]undefined空白以上各级的颜色,从浅到深,优先于 colorTheme未发布
minimumColorstringundefined空白日的颜色未发布
thresholdsnumber[]undefined空白以上每一级的最小值,升序。不传时按数值占最大值的比例向上取整分级未发布
sizesmall | medium | largemedium格子和文字的大小未发布
xGapnumber | stringundefined列间距,数字是 px,也可以是任意 CSS 长度。默认取尺寸对应的间距未发布
yGapnumber | stringundefined行间距,数字是 px,也可以是任意 CSS 长度。默认取尺寸对应的间距未发布
showWeekLabelsbooleantrue在左侧显示星期未发布
showMonthLabelsbooleantrue在上方显示月份未发布
showColorIndicatorbooleantrue在右下角显示图例未发布
loadingbooleanfalse显示占位格子而不是数值未发布
unitstringundefined提示和无障碍名称里数值后面的单位未发布
tooltipboolean | HeatmapTooltipPropstrue悬停和聚焦时的提示。false 关闭;传对象则作为 Tooltip 的 props未发布
renderTooltip(cell: HeatmapCell) => ReactNodeundefined某一天的提示内容,默认是日期和数值未发布
footerReactNodeundefined底部左侧的内容未发布
indicatorReactNodeundefined替换图例未发布
indicatorLeadingTextReactNodeundefined图例颜色前的文字,默认取语言包里的“少”未发布
indicatorTrailingTextReactNodeundefined图例颜色后的文字,默认取语言包里的“多”未发布
onCellClick(cell: HeatmapCell, event: MouseEvent | KeyboardEvent) => voidundefined点击某一天,或在某一天上按 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 字段。