Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Heatmap 热力图
按天显示数值的日历热力图(GitHub 贡献图那种):一列是一周,一行是星期几,颜色越深数值越大。常用来展示每天的提交、登录、巡检、告警次数。
引入
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum, HeatmapCell } from '@ns/ui'
基础用法
data 是 { date, value } 数组。不写范围时显示到今天为止的 52 周,并往前补齐到一周的第一天(周一),一共 53 列;今天之后的位置留空。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
const data: HeatmapDatum[] = [
{ date: '2026-11-15', value: 2 },
{ date: '2026-11-16', value: 5 },
{ date: '2026-11-17', value: 3 }
]
</script>
<template>
<NsHeatmap :data="data" />
</template>
数据和日期
date可以是'YYYY-MM-DD'(也可以写成'YYYY/MM/DD'、带时间的'2026-11-17 08:30')、毫秒时间戳或Date。- 都按本地时区取年月日:
'2026-11-17'就是 17 日,不会因为被当成 UTC 0 点而在西半球变成 16 日;北京时间 0 点到 8 点之间的时间戳也算当天,不会按 UTC 截断成前一天。带时区的 ISO 时间('2026-11-16T16:30:00Z')先换成本地时间再取日期。 - 同一天有多条时相加,可以直接把明细传进来。
value为null的不计入合计;一天只有null时这一天显示“无数据”。 - 认不出的日期(
'abc'、'2026-02-30'、'2026-11'这种只有年月的)忽略,并在控制台警告条数;不在显示范围里的数据忽略,也不参与计算最大值。
把鼠标移到 11 月 17 日、10 日、3 日和 18 日的格子上看看:
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
const data: HeatmapDatum[] = [
// 三种写法都是 2026-11-17,这一天显示 6
{ date: '2026-11-17', value: 1 },
{ date: new Date(2026, 10, 17, 9, 30), value: 2 },
{ date: new Date(2026, 10, 17, 21, 0).getTime(), value: 3 },
// 斜杠、带时间的写法也认
{ date: '2026/11/10', value: 2 },
{ date: '2026-11-03 08:30', value: 4 },
// 这一天只有 null,显示“无数据”
{ date: '2026-11-18', value: null }
]
</script>
<template>
<NsHeatmap :data="data" start="2026-10-01" end="2026-11-30" />
</template>
显示一整年
year 显示这一年的 1 月 1 日到 12 月 31 日,写了它时 start、end 不起作用。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:2025 年的每一天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 11
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const data: HeatmapDatum[] = Array.from({ length: 365 }, (_, i) => ({
date: new Date(2025, 0, 1 + i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" :year="2025" />
</template>
指定起止日期
start、end 写法同 date。只写 end 时从 end 往前 52 周;start 晚于 end 时自动对调并警告。第一周 start 之前、最后一周 end 之后的位置留空。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:2026-03-04 到 2026-06-30 的每一天,用固定种子的伪随机数生成,每次打开都一样
let seed = 5
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const data: HeatmapDatum[] = Array.from({ length: 119 }, (_, i) => ({
date: new Date(2026, 2, 4 + i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" start="2026-03-04" end="2026-06-30" />
</template>
颜色等级
颜色分 5 级:
| 等级 | 条件 | 默认颜色(primary) |
|---|---|---|
| 0 | 没有数据、null、0 或负数 | 填充色 --ns-fill-color |
| 1 | 0 < value ≤ max × 1/4 | 主色和背景色 3 : 7 混合 |
| 2 | max × 1/4 < value ≤ max × 2/4 | 主色和背景色 5 : 5 混合 |
| 3 | max × 2/4 < value ≤ max × 3/4 | 主色和背景色 7 : 3 混合 |
| 4 | value > max × 3/4(超过 max 也算) | 主色 --ns-color-primary |
max默认取显示范围里每天合计的最大值。数据里有个别特别大的值、其他格子都很浅时,可以手动写一个max。- 颜色由主题变量混出来,换配色方案、切暗色主题时自动跟着变;暗色主题下 0 级是比背景亮一档的深灰,1 到 4 级由暗到亮。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" :max="10" />
</template>
下面两个热力图的数据一样,只有今天是 100,其他日子都在 12 以内。上面不写 max,最大值按 100 算,其他有数据的格子都是最浅的 1 级;下面写了 :max="12",颜色就分开了,今天超过 max 仍是最深的 4 级:
<script setup lang="ts">
import { NsHeatmap, NsSpace } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 140 天,用固定种子的伪随机数生成,每次打开都一样;今天是一个特别大的值
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 140 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: i === 0 ? 100 : random() < 0.3 ? null : Math.round(random() * 12)
}))
const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 139)
</script>
<template>
<NsSpace direction="vertical" align="start">
<span class="caption">不写 max(按 100 算)</span>
<NsHeatmap :data="data" :start="start" />
<span class="caption">:max="12"</span>
<NsHeatmap :data="data" :start="start" :max="12" />
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
配色
type 用主题的哪种功能色:primary(默认)、success、warning、danger、info、help。要 GitHub 那样的绿色用 success。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" type="success" />
</template>
6 种配色放在一起对比(只显示最近 20 周):
<script setup lang="ts">
import { NsHeatmap, NsSpace } from '@ns/ui'
import type { HeatmapDatum, HeatmapType } from '@ns/ui'
// 演示数据:今天往前 140 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 140 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 139)
const types: HeatmapType[] = ['primary', 'success', 'warning', 'danger', 'info', 'help']
</script>
<template>
<div class="grid">
<NsSpace v-for="type in types" :key="type" direction="vertical" align="start">
<span class="caption">{{ type }}</span>
<NsHeatmap :data="data" :start="start" :type="type" size="small" />
</NsSpace>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
gap: var(--ns-spacing-4);
}
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
自定义颜色
colors 依次是 0 级到 4 级的 5 个颜色,少写的等级仍用 type 的颜色(个数不是 5 时控制台会警告)。写死的颜色不会跟着暗色主题变,需要的话自己按主题换一组,或者写成 CSS 变量(如 'var(--my-level-1)')。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
const colors = ['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39']
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" :colors="colors" />
</template>
一周从周日开始
first-day-of-week 默认 1(周一在第一行)。写 0 或 7 时周日在第一行,和 GitHub 一样;也可以写 2 - 6。星期标签始终标在周一、周三、周五这三行。写法和 NsCalendar 一致:0 和 7 都是周日,超出范围的按 7 取余。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" :first-day-of-week="0" />
</template>
同一段数据(最近 12 周)分别从周一、周日、周三开始,看左边星期标签的位置变化:
<script setup lang="ts">
import { NsHeatmap, NsSpace } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 84 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 84 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 83)
</script>
<template>
<NsSpace wrap size="large" align="start">
<NsSpace direction="vertical" align="start">
<span class="caption">1:周一(默认)</span>
<NsHeatmap :data="data" :start="start" />
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="caption">0:周日</span>
<NsHeatmap :data="data" :start="start" :first-day-of-week="0" />
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="caption">3:周三</span>
<NsHeatmap :data="data" :start="start" :first-day-of-week="3" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
不同尺寸
size 有 large、default、small 三种:
| 尺寸 | 格子 | 格子间距 | 标签和图例的字号 |
|---|---|---|---|
| large | 14px | 4px | 14px |
| default | 11px | 3px | 12px |
| small | 9px | 2px | 12px |
不写时跟随 NsConfigProvider 的 size,都没有时是 default。一年 53 列时宽度大约是 980 / 770 / 610px。
<script setup lang="ts">
import { NsHeatmap, NsSpace } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsSpace direction="vertical" fill>
<span class="caption">large</span>
<NsHeatmap :data="data" size="large" />
<span class="caption">default</span>
<NsHeatmap :data="data" />
<span class="caption">small</span>
<NsHeatmap :data="data" size="small" />
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
格子间距
x-gap、y-gap 改左右、上下的间距,数字按 px,也可以写 '0.25em' 这类长度;不写时按尺寸取上表的值。两个可以只写一个。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" :x-gap="6" :y-gap="6" />
</template>
只显示最近 12 周,对比几种写法:
<script setup lang="ts">
import { NsHeatmap, NsSpace } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 84 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 84 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 83)
</script>
<template>
<NsSpace wrap size="large" align="start">
<NsSpace direction="vertical" align="start">
<span class="caption">不写(3px)</span>
<NsHeatmap :data="data" :start="start" />
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="caption">:x-gap="0" :y-gap="0"</span>
<NsHeatmap :data="data" :start="start" :x-gap="0" :y-gap="0" />
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="caption">:x-gap="8"</span>
<NsHeatmap :data="data" :start="start" :x-gap="8" />
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="caption">y-gap="0.5em"</span>
<NsHeatmap :data="data" :start="start" y-gap="0.5em" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
提示
鼠标悬停或键盘聚焦格子时显示“2026-11-17:3 次”,没有数据时显示“2026-11-17:无数据”。
unit改单位,例如unit="小时";写空字符串时只显示数值。tooltip插槽自定义内容,参数是{ date, value, level }。:tooltip="false"不显示提示。
所有格子共用一个提示框,跟着当前格子移动,一年 371 个格子也只有一个提示框。提示框不接收鼠标事件(不会挡住下面的格子),所以里面放链接、按钮点不到,要交互请用 cell-click。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
</script>
<template>
<NsHeatmap :data="data" unit="小时" />
<NsHeatmap :data="data" style="margin-top: 16px">
<template #tooltip="{ date, value }">
<div>{{ date }}</div>
<div>{{ value === null ? '没有提交' : `提交 ${value} 次` }}</div>
</template>
</NsHeatmap>
</template>
只显示最近 12 周,对比 unit=""、带 level 的提示插槽和关掉提示:
<script setup lang="ts">
import { NsHeatmap, NsSpace } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 84 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 84 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 83)
</script>
<template>
<NsSpace wrap size="large" align="start">
<NsSpace direction="vertical" align="start">
<span class="caption">unit="":只显示数值</span>
<NsHeatmap :data="data" :start="start" unit="" />
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="caption">插槽里显示 level</span>
<NsHeatmap :data="data" :start="start" type="success">
<template #tooltip="{ date, value, level }">
{{ date }}:{{ value ?? '无数据' }}({{ level }} 级)
</template>
</NsHeatmap>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span class="caption">:tooltip="false"</span>
<NsHeatmap :data="data" :start="start" :tooltip="false" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
点击格子
点击格子,或者格子聚焦时按回车、空格,触发 cell-click,参数是 { date, value, level } 和原生事件。date 是 'YYYY-MM-DD',value 没有数据时是 null。点范围外的空位、标签不触发,加载中也不触发。
<script setup lang="ts">
import { NsHeatmap, NsMessage } from '@ns/ui'
import type { HeatmapCell, HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const onCellClick = (cell: HeatmapCell) => {
NsMessage(`${cell.date}:${cell.value ?? '无数据'}(${cell.level} 级)`)
}
</script>
<template>
<NsHeatmap :data="data" @cell-click="onCellClick" />
</template>
标签、图例和底部
show-week-labels、show-month-labels、show-legend分别控制左边的星期标签(一、三、五)、上面的月份标签(1月 … 12月)和右下角的“少 … 多”图例,默认都显示。- 只占一两列的月份(范围两头不满三周的月份)不显示文字,免得和旁边的月份挤在一起。
less-text、more-text改图例两边的文字,例如英文界面写less-text="Less" more-text="More"。footer插槽显示在底部左边,图例在右边。
<script setup lang="ts">
import { NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const total = data.reduce((sum, item) => sum + (item.value ?? 0), 0)
</script>
<template>
<NsHeatmap :data="data" less-text="Less" more-text="More">
<template #footer>过去一年共 {{ total }} 次</template>
</NsHeatmap>
</template>
勾选框控制三部分是否显示(只显示最近 20 周):
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsHeatmap, NsSpace } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 140 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 140 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 139)
const showWeekLabels = ref(true)
const showMonthLabels = ref(true)
const showLegend = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsCheckbox v-model="showWeekLabels">星期标签(show-week-labels)</NsCheckbox>
<NsCheckbox v-model="showMonthLabels">月份标签(show-month-labels)</NsCheckbox>
<NsCheckbox v-model="showLegend">图例(show-legend)</NsCheckbox>
</NsSpace>
<NsHeatmap
:data="data"
:start="start"
:show-week-labels="showWeekLabels"
:show-month-labels="showMonthLabels"
:show-legend="showLegend"
/>
</NsSpace>
</template>
加载中
loading 为 true 时格子显示成一起明暗闪烁的灰色(系统开了“减少动态效果”时不闪烁),不显示提示,点击不触发事件。日期范围不依赖数据,所以加载前后格子的位置、热力图的大小不变。勾选框切换加载状态:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsHeatmap } from '@ns/ui'
import type { HeatmapDatum } from '@ns/ui'
// 演示数据:今天往前 371 天,用固定种子的伪随机数生成,每次打开都一样;约三成的日子没有数据
let seed = 7
const random = () => {
seed = (seed * 16807) % 2147483647
return seed / 2147483647
}
const today = new Date()
const data: HeatmapDatum[] = Array.from({ length: 371 }, (_, i) => ({
date: new Date(today.getFullYear(), today.getMonth(), today.getDate() - i),
value: random() < 0.3 ? null : Math.round(random() * 12)
}))
const loading = ref(true)
</script>
<template>
<NsCheckbox v-model="loading">加载中(loading)</NsCheckbox>
<NsHeatmap :data="data" :loading="loading" style="margin-top: 12px" />
</template>
键盘操作
格子用 roving tabindex:整个热力图只占一个 Tab 位置,进入时焦点在今天(今天不在范围里时是第一天),之后停在上次聚焦的格子。
- 上 / 下键:前一天 / 后一天(周日按下键到下一周的周一);
- 左 / 右键:前一周 / 后一周的同一天;
- Home / End:这一行(同一个星期几)的第一格 / 最后一格;
- Ctrl + Home / End(Mac 上 ⌘ + Home / End):范围的第一天 / 最后一天;
- 回车、空格:触发
cell-click; - Esc:收起提示(提示开着时会阻止默认行为,放在对话框里不会把对话框一起关掉)。
到了范围的边上不再移动。聚焦格子时显示提示。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| data | HeatmapDatum[] | [] | 数据 { date, value }[],同一天有多条时相加 |
| year | number | - | 显示一整年(1 月 1 日到 12 月 31 日),写了它时 start、end 不起作用 |
| start | string | number | Date | - | 第一天。不写时是 end 往前 52 周,并往前补齐到一周的第一天 |
| end | string | number | Date | 今天 | 最后一天 |
| first-day-of-week | number | 1 | 一周从星期几开始:1 是周一,0 或 7 是周日 |
| max | number | - | 4 级颜色对应的最大值,默认取显示范围里每天合计的最大值;超过它的都是最深的一级 |
| type | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help' | 'primary' | 配色:用主题的哪种功能色 |
| colors | string[] | - | 自定义颜色,依次是 0 级到 4 级共 5 个;少写的等级用 type 的颜色 |
| show-week-labels | boolean | true | 是否显示左边的星期标签 |
| show-month-labels | boolean | true | 是否显示上面的月份标签 |
| show-legend | boolean | true | 是否显示右下角的“少 … 多”图例 |
| less-text | string | '少' | 图例左边的文字 |
| more-text | string | '多' | 图例右边的文字 |
| tooltip | boolean | true | 悬停、聚焦格子时是否显示提示 |
| unit | string | '次' | 提示和可读名称里数值后面的单位;空字符串时不显示单位 |
| loading | boolean | false | 是否加载中 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随 NsConfigProvider 的 size,都没有时是 'default' |
| x-gap | number | string | - | 格子的左右间距,数字按 px;不写时按尺寸是 4 / 3 / 2px |
| y-gap | number | string | - | 格子的上下间距,写法同 x-gap |
HeatmapDatum
| 属性 | 类型 | 说明 |
|---|---|---|
| date | string | number | Date | 日期,按本地时区取年月日 |
| value | number | null | 数值;null 表示没有数据。同一天多条相加 |
HeatmapCell
cell-click 事件和 tooltip 插槽的参数。
| 属性 | 类型 | 说明 |
|---|---|---|
| date | string | 'YYYY-MM-DD',本地日期 |
| value | number | null | 这一天的合计,没有数据时是 null |
| level | 0 | 1 | 2 | 3 | 4 | 颜色等级 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| cell-click | (cell: HeatmapCell, event: MouseEvent | KeyboardEvent) | 点击格子,或格子聚焦时按回车、空格;范围外的空位和加载中不触发 |
Slots
| 插槽 | 参数 | 说明 |
|---|---|---|
| tooltip | { date, value, level } | 自定义提示的内容,默认是“2026-11-17:3 次” |
| footer | - | 底部左边的内容(图例在右边),例如“过去一年共 1234 次” |
方法
没有对外暴露的方法。
类型
import type {
HeatmapProps,
HeatmapEmits,
HeatmapSlots,
HeatmapSize,
HeatmapType,
HeatmapDateInput,
HeatmapDatum,
HeatmapCell,
HeatmapLevel
} from '@ns/ui'
type HeatmapSize = 'large' | 'default' | 'small'
type HeatmapType = 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help'
type HeatmapDateInput = string | number | Date
type HeatmapLevel = 0 | 1 | 2 | 3 | 4
interface HeatmapDatum {
date: HeatmapDateInput
value: number | null
}
interface HeatmapCell {
date: string
value: number | null
level: HeatmapLevel
}
interface HeatmapProps {
data?: HeatmapDatum[]
year?: number
start?: HeatmapDateInput
end?: HeatmapDateInput
firstDayOfWeek?: number
max?: number
type?: HeatmapType
colors?: string[]
showWeekLabels?: boolean
showMonthLabels?: boolean
showLegend?: boolean
lessText?: string
moreText?: string
tooltip?: boolean
unit?: string
loading?: boolean
size?: HeatmapSize
xGap?: number | string
yGap?: number | string
}
interface HeatmapSlots {
tooltip?: (props: HeatmapCell) => unknown
footer?: () => unknown
}
interface HeatmapEmits {
'cell-click': [cell: HeatmapCell, event: MouseEvent | KeyboardEvent]
}
注意事项
- “今天”在组件渲染、或者
data/ 范围变化时取一次,不会过了 0 点自动刷新;页面要一直开着时,可以到点后重新给end赋值。 - 默认 53 列大约 770px 宽。容器比它窄时热力图横向滚动,不会撑破容器。
- 整个热力图是
role="grid"(选它而不是role="img",是因为每个格子能用键盘逐个查看、能点击,读屏软件也能读出每一天的数值),可读名称是“热力图:2025-11-17 至 2026-11-17,120 天有数据,合计 456 次”。每个格子的名称是“2026-11-17 星期二:3 次”;月份、星期标签、空位和图例只是看的,对读屏软件隐藏。用了tooltip插槽时,格子还会用aria-describedby指向提示框。 - 提示框挂在
body上,层级跟随NsConfigProvider的zIndex;默认在格子上方,上方放不下时翻到下方。 colors写死的颜色不跟随暗色主题;用type时颜色由主题变量混出来,两套主题都不用另外处理。- 浮点数相加的误差会去掉(0.1 + 0.2 显示 0.3),其他数值原样显示,不做千分位或小数位格式化,需要时用
tooltip插槽。