Heatmap

heatmap

热力图 · 网格色阶映射(value→bucket→primary 透明度档·纯函数 buildMatrix/bucketize 可测) + emptyCellTone 区分「无数据」与「值为 0」 + 小数值域 domain/valueFormat 百分比 + 色阶图例 + 行列标签 + 原生 hover 提示 + 点击下钻 · 代码热点/贡献活动/覆盖率·库内首个热力图

用法

基础用法

传稀疏点集 data + 行列标签，自动按值映射到主色透明度档。

支付

订单

搜索

推送

周一周二周三周四周五周六周日

tsx

<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} cellSize={18} />

贡献活动图

GitHub 风格的 12 周活动热力，格子调小更紧凑。

一

二

三

四

五

六

日

W1W2W3W4W5W6W7W8W9W10W11W12

tsx

<Heatmap
  data={contribData}
  xLabels={weeks}
  yLabels={["一", "二", "三", "四", "五", "六", "日"]}
  cellSize={14}
/>

色阶档数

colorScale 控制色阶分档，档数越多过渡越细腻。

支付

订单

搜索

推送

周一周二周三周四周五周六周日

tsx

<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} colorScale={9} />

无标签紧凑

showLabels={false} 隐藏行列标签，适合放进卡片做缩略图。

tsx

<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} showLabels={false} cellSize={12} />

小数值域 / 百分比 + 图例

比率数据（0–1）传 domain 收紧值域铺满色阶；valueFormat 让 tooltip 与图例自动带 %；showLegend 显示色阶图例。

一班

二班

三班

四班

有理数整式方程函数几何

50%90%

tsx

<Heatmap
  data={masteryData}            // value 是 0.5~0.85 的掌握率
  xLabels={TOPICS}
  yLabels={CLASSES}
  domain={[0.5, 0.9]}           // 按值域比例分档，低区间也能铺满色阶
  valueFormat={(v) => `${Math.round(v * 100)}%`}
  showLegend
  cellSize={18}
/>

无数据 vs 值为 0

缺席格（data 里没有这个点）默认与 0 档同色；传 emptyCellTone 把它涂成独立样式，才能和「真实的 0」分开。图例会自动补一块「无数据」样例。

一班

二班

三班

四班

有理数整式方程函数几何

0%100%无数据

tsx

<Heatmap
  data={masterySparse}          // 三班的函数/几何整格缺席，四班·方程是真实 0
  xLabels={TOPICS}
  yLabels={CLASSES}
  domain={[0, 1]}
  valueFormat={(v) => `${Math.round(v * 100)}%`}
  emptyCellTone="repeating-linear-gradient(45deg, var(--color-border) 0 2px, transparent 2px 4px)"
  showLegend
  formatTooltip={(c) => (c.empty ? `${c.y} · ${c.x}：未作答` : `${c.y} · ${c.x}：${Math.round(c.value * 100)}%`)}
/>

自定义提示 + 下钻

formatTooltip 自定义悬停文案；传 onCellClick 后格子变为可点击按钮。

支付

订单

搜索

推送

周一周二周三周四周五周六周日

tsx

<Heatmap
  data={data}
  xLabels={WEEKDAYS}
  yLabels={MODULES}
  formatTooltip={(c) => `${c.y} 在 ${c.x}：${c.value} 个问题`}
  onCellClick={(c) => alert(`${c.y} · ${c.x}`)}
/>

何时用

把稀疏的 {x, y, value} 点集按二维网格展开、用色阶强度表达数值密度时用（贡献活动墙、模块×时间问题热点、覆盖率矩阵）。需要可排序、可分页、单元格内放富内容的表格走 Table / ProTable；这里只做「强度即颜色」的密度可视化。

导入

import { Heatmap, buildMatrix, bucketize } from "@hulianui/ui"

Props

名称	类型	默认	说明
data*	`HeatCell[]`	—	稀疏点集 `{x, y, value}`。
xLabels	`(string｜number)[]`	从 data 推导	显式列标签。
yLabels	`(string｜number)[]`	从 data 推导	显式行标签。
colorScale	`number`	`5`	色阶档数。
max	`number`	数据最大值	满值（决定色阶顶档）；`domain` 同传时以 domain 为准。
domain	`[number, number]`	`[0, max]`	显式值域，按 `(value-min)/(max-min)` 比例分档；小数/比率数据传 `[0, 1]` 或收紧到实际区间（如掌握率 `[0.5, 0.9]`）铺满色阶。value ≤ min 落 0 档。
valueFormat	`(value: number) => string`	`String`	数值显示格式化，tooltip 默认文案与图例共用（比率转百分比：`(v) => \`${Math.round(v*100)}%\``）。优先于 unit。
unit	`string`	—	数值后缀（`"%"`、`" 次"`），拼在原始值后；要换算用 valueFormat。
emptyCellTone	`string`	—	缺席格（`data` 里没有这个点）的背景，任意 CSS 颜色/渐变。不传则缺席格与 0 档同色（保持既有视觉）。传了之后色阶图例会多一块「无数据」样例。
showLegend	`boolean`	`false`	色阶图例（值域下限 → colorScale+1 个色块 → 上限，标签走 valueFormat/unit；`emptyCellTone` 已传时末尾追加「无数据」块）。
cellSize	`number`	`14`	格子边长 px。
gap	`number`	`3`	格间距 px。
showLabels	`boolean`	`true`	是否显示行/列标签。
formatTooltip	`(cell: HeatmapCellInfo) => string`	—	悬停原生提示文案（返回字符串）。缺席格拿到 `cell.empty === true` 且 `cell.value` 为 0，先判 `empty` 再用 `value`。
className	`string`	—	—

HeatmapCellInfo（formatTooltip / onCellClick 的入参）：

字段	类型	说明
x / y	`string｜number`	列 / 行标签。
value	`number`	该格的值；缺席格恒为 `0`，别拿它判断「有没有数据」。
empty	`boolean`	该格在 `data` 里是否缺席。组件始终传；类型上可选只为不破坏旧标注。

Events

事件	类型	说明
onCellClick	`(cell: HeatmapCellInfo) => void`	点击格子下钻。

禁忌 / 坑

注意 data 的 value 应为确定性数据：showcase 用伪随机公式而非 Math.random() 生成，避免 SSR/CSR 首帧色阶不一致。色阶顶档由 max（缺省取数据最大值）决定，跨多张图对比时建议显式传同一 max（或同一 domain）才能横向可比。

unit 是纯后缀拼接：0–1 比率数据配 unit="%" 会显示「0.55%」——比率转百分比必须用 valueFormat。
0.6.x 起小数数据不传 max 时按真实数据最大值分档（旧版会抬到 1）；依赖旧行为的显式传 max={1}。
domain 的 min 是「0 档下限」：value ≤ min 渲染为最浅档，min 别设成有效数据的下界值本身（如掌握率最低 0.55 就设 0.5）。
「无数据」默认与「值为 0」同色：缺席格默认仍走 0 档色（贡献活动墙里「这天没提交」本来就该是最浅色，不能改样）。当两者语义相反时——「这个班没作答这个考点」不是教学信号，「掌握率真的 0%」是最红的红灯——必须显式传 emptyCellTone 才画得开，光看图发现不了这个合并。
判断有没有数据只能看 cell.empty，不能看 cell.value === 0：缺席格的 value 被兜底成 0（保持 formatTooltip/onCellClick 的旧签名不破）。默认 tooltip 与 aria-label 对缺席格已自动改说「无数据」，自定义 formatTooltip 要自己判 empty，否则会印成「0」。
buildMatrix(...).get(y, x) 0.13 起缺席返回 undefined（旧版返回 0）；直接消费这个纯函数的代码要自己兜底，比如 get(y, x) ?? 0。

Playground

色阶档数格子边长显示标签

支付

订单

搜索

推送

周一周二周三周四周五周六周日

<Heatmap data={data} colorScale={5} cellSize={16} />

用法

基础用法

传稀疏点集 data + 行列标签，自动按值映射到主色透明度档。

支付

订单

搜索

推送

周一周二周三周四周五周六周日

tsx

<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} cellSize={18} />

贡献活动图

GitHub 风格的 12 周活动热力，格子调小更紧凑。

一

二

三

四

五

六

日

W1W2W3W4W5W6W7W8W9W10W11W12

tsx

<Heatmap
  data={contribData}
  xLabels={weeks}
  yLabels={["一", "二", "三", "四", "五", "六", "日"]}
  cellSize={14}
/>

色阶档数

colorScale 控制色阶分档，档数越多过渡越细腻。

支付

订单

搜索

推送

周一周二周三周四周五周六周日

tsx

<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} colorScale={9} />

无标签紧凑

showLabels={false} 隐藏行列标签，适合放进卡片做缩略图。

tsx

<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} showLabels={false} cellSize={12} />

小数值域 / 百分比 + 图例

比率数据（0–1）传 domain 收紧值域铺满色阶；valueFormat 让 tooltip 与图例自动带 %；showLegend 显示色阶图例。

一班

二班

三班

四班

有理数整式方程函数几何

50%90%

tsx

<Heatmap
  data={masteryData}            // value 是 0.5~0.85 的掌握率
  xLabels={TOPICS}
  yLabels={CLASSES}
  domain={[0.5, 0.9]}           // 按值域比例分档，低区间也能铺满色阶
  valueFormat={(v) => `${Math.round(v * 100)}%`}
  showLegend
  cellSize={18}
/>

无数据 vs 值为 0

缺席格（data 里没有这个点）默认与 0 档同色；传 emptyCellTone 把它涂成独立样式，才能和「真实的 0」分开。图例会自动补一块「无数据」样例。

一班

二班

三班

四班

有理数整式方程函数几何

0%100%无数据

tsx

<Heatmap
  data={masterySparse}          // 三班的函数/几何整格缺席，四班·方程是真实 0
  xLabels={TOPICS}
  yLabels={CLASSES}
  domain={[0, 1]}
  valueFormat={(v) => `${Math.round(v * 100)}%`}
  emptyCellTone="repeating-linear-gradient(45deg, var(--color-border) 0 2px, transparent 2px 4px)"
  showLegend
  formatTooltip={(c) => (c.empty ? `${c.y} · ${c.x}：未作答` : `${c.y} · ${c.x}：${Math.round(c.value * 100)}%`)}
/>

自定义提示 + 下钻

formatTooltip 自定义悬停文案；传 onCellClick 后格子变为可点击按钮。

支付

订单

搜索

推送

周一周二周三周四周五周六周日

tsx

<Heatmap
  data={data}
  xLabels={WEEKDAYS}
  yLabels={MODULES}
  formatTooltip={(c) => `${c.y} 在 ${c.x}：${c.value} 个问题`}
  onCellClick={(c) => alert(`${c.y} · ${c.x}`)}
/>

何时用

Props

名称	类型	默认	说明
data*	`HeatCell[]`	—	稀疏点集 `{x, y, value}`。
xLabels	`(string｜number)[]`	从 data 推导	显式列标签。
yLabels	`(string｜number)[]`	从 data 推导	显式行标签。
colorScale	`number`	`5`	色阶档数。
max	`number`	数据最大值	满值（决定色阶顶档）；`domain` 同传时以 domain 为准。
domain	`[number, number]`	`[0, max]`	显式值域，按 `(value-min)/(max-min)` 比例分档；小数/比率数据传 `[0, 1]` 或收紧到实际区间（如掌握率 `[0.5, 0.9]`）铺满色阶。value ≤ min 落 0 档。
valueFormat	`(value: number) => string`	`String`	数值显示格式化，tooltip 默认文案与图例共用（比率转百分比：`(v) => \`${Math.round(v*100)}%\``）。优先于 unit。
unit	`string`	—	数值后缀（`"%"`、`" 次"`），拼在原始值后；要换算用 valueFormat。
emptyCellTone	`string`	—	缺席格（`data` 里没有这个点）的背景，任意 CSS 颜色/渐变。不传则缺席格与 0 档同色（保持既有视觉）。传了之后色阶图例会多一块「无数据」样例。
showLegend	`boolean`	`false`	色阶图例（值域下限 → colorScale+1 个色块 → 上限，标签走 valueFormat/unit；`emptyCellTone` 已传时末尾追加「无数据」块）。
cellSize	`number`	`14`	格子边长 px。
gap	`number`	`3`	格间距 px。
showLabels	`boolean`	`true`	是否显示行/列标签。
formatTooltip	`(cell: HeatmapCellInfo) => string`	—	悬停原生提示文案（返回字符串）。缺席格拿到 `cell.empty === true` 且 `cell.value` 为 0，先判 `empty` 再用 `value`。
className	`string`	—	—

HeatmapCellInfo（formatTooltip / onCellClick 的入参）：

字段	类型	说明
x / y	`string｜number`	列 / 行标签。
value	`number`	该格的值；缺席格恒为 `0`，别拿它判断「有没有数据」。
empty	`boolean`	该格在 `data` 里是否缺席。组件始终传；类型上可选只为不破坏旧标注。

事件

类型

说明

onCellClick

(cell: HeatmapCellInfo) => void

点击格子下钻。

禁忌 / 坑

unit 是纯后缀拼接：0–1 比率数据配 unit="%" 会显示「0.55%」——比率转百分比必须用 valueFormat。

0.6.x 起小数数据不传 max 时按真实数据最大值分档（旧版会抬到 1）；依赖旧行为的显式传 max={1}。

domain 的 min 是「0 档下限」：value ≤ min 渲染为最浅档，min 别设成有效数据的下界值本身（如掌握率最低 0.55 就设 0.5）。

「无数据」默认与「值为 0」同色：缺席格默认仍走 0 档色（贡献活动墙里「这天没提交」本来就该是最浅色，不能改样）。当两者语义相反时——「这个班没作答这个考点」不是教学信号，「掌握率真的 0%」是最红的红灯——必须显式传 emptyCellTone 才画得开，光看图发现不了这个合并。

判断有没有数据只能看 cell.empty，不能看 cell.value === 0：缺席格的 value 被兜底成 0（保持 formatTooltip/onCellClick 的旧签名不破）。默认 tooltip 与 aria-label 对缺席格已自动改说「无数据」，自定义 formatTooltip 要自己判 empty，否则会印成「0」。

buildMatrix(...).get(y, x) 0.13 起缺席返回 undefined（旧版返回 0）；直接消费这个纯函数的代码要自己兜底，比如 get(y, x) ?? 0。

Heatmap

用法

基础用法

贡献活动图

色阶档数

无标签紧凑

小数值域 / 百分比 + 图例

无数据 vs 值为 0

自定义提示 + 下钻

何时用

导入

Props

Events

禁忌 / 坑

相关

Playground

Heatmap

用法

基础用法

贡献活动图

色阶档数

无标签紧凑

小数值域 / 百分比 + 图例

无数据 vs 值为 0

自定义提示 + 下钻

何时用

导入

Props

Events

禁忌 / 坑

相关

Playground