前端UI组件【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址https://gitcode.com/gh_mirrors/na/naive-ui点击查看免费下载热力图Heatmap组件自 Naive UI2.43.0版本开始提供用于以 GitHub 贡献墙式的周列 × 星期行网格展示时间序列数据如每日活跃度、提交次数、打卡记录。本文基于 组件文档 展开结合 核心实现 与 数据工具函数 源码系统讲解数据模型、全部 Props / Slots、内置与自定义配色、加载态以及 mock 数据用法帮助你直接在自己的 Vue 3 项目中落地一个可复制的热力图方案。一、组件概览与使用前提Heatmap 用一张日历表来展示数据每一列代表一周每一行代表星期周一到周日每个单元格是一个带颜色的方块颜色深浅映射数值大小。它在内部基于 date-fns 中按需导出可随naive-ui的 tree-shaking 机制使用template n-heatmap :datadata / /template script setup langts import { heatmapMockData } from naive-ui const data heatmapMockData(recent) /script使用前提重要官方文档明确提示颜色相关属性active-colors和minimum-color的优先级高于color-theme。如果三个属性同时设置实际生效的是active-colors与minimum-color因此文档建议不要同时设置当三者都不设置时组件使用 Naive UI 内置的类 GitHub默认配色。二、数据模型timestamp value 的结构约定data是组件的核心输入其类型定义位于 public-types.tsexport type HeatmapData HeatmapDataItem[] export interface HeatmapDataItem { timestamp: number // 时间戳毫秒 value?: number | null // 数值可选 }字段语义依据 utils/index.ts 的completeDataGaps实现timestamp毫秒级时间戳用于把每一天定位到日历网格的某个单元格。value该天的数值驱动颜色深浅。undefined或null的格子不渲染方块但保留占位缺失的日期会被自动补全为value: 0。数据会被按时间戳排序并补全首日所在周与末日所在周之间的所有空白日期确保网格完整。下面的示例直接来自 官方基础用法演示 的数据统计逻辑展示了如何基于HeatmapData计算总天数、空白天、最大值与平均值import { computed, ref } from vue import { heatmapMockData } from naive-ui const value refrecent | number(recent) const yearData computed(() heatmapMockData(value.value)) const dataStats computed(() { const data yearData.value const total data.length const zeros data.filter(d d.value 0).length const maxValue Math.max(...data.map(d d.value ?? 0)) const avgValue Math.round( (data.reduce((sum, d) sum (d.value ?? 0), 0) / total) * 100 ) / 100 return { total, zeros, maxValue, avgValue, zeroPercent: Math.round((zeros / total) * 100) } })日期对齐first-day-of-week与fill-calendar-leading网格的周从哪一天开始由first-day-of-week决定取值范围0 | 1 | 2 | 3 | 4 | 5 | 60表示周一Naive UI 的约定与 JavaScriptDate.getDay()的 0周日不同6表示周日默认值为0。源码中通过 date-picker 的工具函数 将 Naive 的语义转换为 date-fns 的weekStartsOn。测试用例 Heatmap.spec.tsx 分别验证了0 / 1 / 6三种起始日均可正常工作。fill-calendar-leading默认false控制是否填满日历网格的头部false默认数据首日之前的周内空白用value: null占位不显示方块true这些空白格子被填充为value: 0显示最浅色方块适合 GitHub 风格的最近一年整块视图。官方基础演示中正是用:fill-calendar-leadingvalue recent在最近一年模式下开启它。三、Heatmap Props 完整参考以下表格完整继承自 组件文档类型为HeatmapProps定义见 Heatmap.tsx名称类型相关类型默认值说明版本active-colorsstring[]-undefined颜色数组按从浅到深的顺序排列优先级高于color-theme2.43.0color-themegreen \| blue \| orange \| purple \| redHeatmapColorThemeundefined内置颜色主题2.43.0dataArray{ timestamp: number, value?: number \| null }HeatmapData,HeatmapDataItem[]热力图数据包含日期和数值2.43.0first-day-of-week0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6HeatmapFirstDayOfWeek0一周的开始日0表示周一6表示周日2.43.0fill-calendar-leadingboolean-false是否填满日历网格的头部适用于 GitHub 风格的最近一年视图2.43.0loadingboolean-false是否显示加载状态2.43.0loading-dataArray{ timestamp: number, value?: number \| null }HeatmapData,HeatmapDataItemundefined加载状态下展示的数据单元格value为null时不展示 cell 但占位设为任意非null值则展示加载状态2.43.0minimum-colorstring-undefined热力图最小颜色默认为active-colors中的第一个颜色2.43.0show-color-indicatorboolean-true是否显示底部的颜色层级指示器2.43.0show-month-labelsboolean-true是否显示月份标签2.43.0show-week-labelsboolean-true是否显示周标签2.43.0sizesmall \| medium \| large-medium热力图尺寸2.43.0tooltipboolean \| TooltipProps-falsetooltip 配置false为禁用对象为TooltipProps2.43.0x-gapnumber \| string-undefined水平方向间距2.43.0y-gapnumber \| string-undefined垂直方向间距2.43.0颜色合并优先级源码验证Heatmap.tsx 中的mergedColorsRef精确实现了文档所说的优先级规则const mergedMininumColor props.minimumColor || builtInMinimumColor const theme props.colorTheme heatmapColorThemes[props.colorTheme] const mergedActiveColors props.activeColors || theme || builtInActiveColors return [mergedMininumColor, ...mergedActiveColors]即minimum-color优先于主题内置最小色active-colors优先于color-themecolor-theme优先于主题默认值。最终渲染用的颜色数组是[最小色, 活跃色1, 活跃色2, ...]。颜色如何映射到数值颜色分级逻辑在 utils/index.ts 的calcColorByValue中取value / maxValue的比例上限 1按颜色数组长度分层Math.ceil(ratio * (len-1))数值 ≤ 0 或为null时一律使用第一个颜色即minimum-color。尺寸与间距的底层默认值三个尺寸对应的单元格尺寸、圆角、间距与字号在 light.ts 中定义rectSize分别为10px / 11px / 12px圆角均为2pxxGap/yGap为2px/3px。当传入x-gap、y-gap数字或 CSS 字符串均可时会通过pxfy覆盖默认值。四、内置主题与自定义颜色使用color-theme内置主题内置主题定义在 theme.ts共 5 套均为 4 级渐深色主题颜色数组浅 → 深green[#c6e48b, #7bc96f, #239a3b, #196127]blue[#c0e7ff, #73b3ff, #0969da, #0550ae]orange[#fed7aa, #fb923c, #ea580c, #c2410c]purple[#e9d5ff, #c084fc, #9333ea, #7c3aed]red[#fecaca, #f87171, #dc2626, #b91c1c]官方主题演示 的用法非常直接script setup langts import { heatmapMockData } from naive-ui const data heatmapMockData() const themes [ { name: 绿色, value: green }, { name: 蓝色, value: blue }, { name: 橙色, value: orange }, { name: 紫色, value: purple }, { name: 红色, value: red } ] as const /script template n-heatmap v-fortheme in themes :keytheme.value :datadata :color-themetheme.value / /template测试 Heatmap.spec.tsx 也对orange / blue / green等主题逐一做了挂载验证。用active-colorsminimum-color自定义颜色官方自定义颜色演示 展示了完整做法active-colors是从浅到深排列的颜色数组minimum-color单独设置最小值零值/空值的颜色。文档特别强调active-colors与minimum-color的优先级高于color-theme二者同时设置时不要再用color-theme。演示中还配合n-color-picker让用户实时改色script setup langts import { heatmapMockData } from naive-ui import { ref } from vue const data heatmapMockData() const customActiveColors ref([#9be9a8, #40c463, #30a14e, #216e39]) const minimumColor ref(#ebedf0) /script template n-heatmap :datadata :active-colorscustomActiveColors :minimum-colorminimumColor / /template五、加载状态loading / loading-dataloading与loading-data配合实现加载态其行为在源码heatmapMatrixRefHeatmap.tsx中有精确体现当loading为true且未提供loading-data时渲染一个固定的7×53 占位矩阵见createLoadingMatrix配合 animationStyle.ts 的闪烁动画展示骨架屏当同时提供loading-data时矩阵基于loading-data构建value为null的格子不展示方块但保留占位value为任意非null值则展示带加载动画的方块loading为false时忽略loading-data正常渲染data。官方基础演示中的做法是直接把yearData同时传给data和loading-data用开关切换n-heatmap :datayearData :loading-datayearData :first-day-of-weekfirstDayOfWeek :loadingloading :sizesize :show-week-labelsshowWeekLabels :show-month-labelsshowMonthLabels :show-color-indicatorshowColorIndicator :fill-calendar-leadingvalue recent /loading开关本身也在 Heatmap.spec.tsx 中被测试覆盖setProps({ loading: true })后组件正常渲染。六、标签控制月份标签、周标签与颜色指示器show-week-labels默认true左侧的星期标签。源码 Heatmap.tsx 会生成 7 个标签并按i % 2 ! 0规则只显示奇数行减少视觉噪音测试验证了开关可正确移除.n-heatmap__week-label-cell。show-month-labels默认true顶部的月份标签。源码按列上首个非空格子的月份进行分组getColsMonth并只保留覆盖周数 ≥ 3 的月份weekCount 3避免标签过挤加载态则使用固定的colSpans [5, 4, 5, 4, 5, 4, 5, 4, 4, 5, 4, 4]保持宽度一致。show-color-indicator默认true底部右侧的颜色层级指示器由 ColorIndicator.tsx 渲染从左到右展示较少 → 较多的渐变色带。七、Tooltip 配置与自定义tooltip属性接受false禁用默认或一个TooltipProps对象即 Naive UI 内置NTooltip的属性如placement、delay等。当tooltip为对象时每个格子会包一层NTooltipRect.tsx 负责具体渲染。配合#tooltip插槽可完全自定义悬浮内容插槽参数类型为HeatmapTooltipSlotProps即{ timestamp: number, value?: number | null }。官方插槽演示 给出了完整范例n-heatmap :datayearData unitactivities :tooltip{ placement: bottom, delay: 500 } template #footer n-text depth3底部显示 tooltip延迟 500ms/n-text /template template #tooltip{ timestamp: date, value: tooltipValue } 活动详情br div{{ new Date(date).toLocaleDateString() }}/div div{{ tooltipValue ?? 0 }}/div /template /n-heatmap八、插槽参考类型为HeatmapSlots定义见 public-types.ts下表完整继承自文档名称参数相关类型说明版本footer()-底部左侧信息插槽与 heatmap table 左边对齐2.43.0indicator()-底部右侧指示器插槽与 heatmap table 右边对齐2.43.0indicator-leading-text()-颜色层级指示器的前置文字2.43.0indicator-trailing-text()-颜色层级指示器的后置文字2.43.0tooltip(props: { timestamp: number, value?: number \| null })HeatmapTooltipSlotProps自定义 tooltip 内容2.43.0使用要点来自官方演示与源码 Heatmap.tsx提供indicator插槽时会完全替换内置的颜色指示器此时show-color-indicator无效indicator-leading-text/indicator-trailing-text只替换指示器两端的文字默认分别为本地化的较少/更多文案取自useLocale(Heatmap)footer与indicator分别位于底部左右两侧与表格对齐这些插槽均有对应的测试覆盖footer/indicator自定义内容的断言见 Heatmap.spec.tsx。n-heatmap :datayearData :show-color-indicatorfalse template #footer n-text depth3左侧信息插槽/n-text /template template #indicator n-text depth3右侧指示器插槽/n-text /template template #tooltip{ timestamp: date, value: tooltipValue } divstrong日期:/strong {{ new Date(date).toLocaleDateString() }}/div divstrong数值:/strong {{ tooltipValue ?? 0 }}/div div v-iftooltipValue ! null tooltipValue 5 n-tag typesuccess sizesmall高活跃度/n-tag /div /template /n-heatmap九、快速上手heatmapMockData生成模拟数据组件文档的 Others 部分给出了一个便于快速调试的导出import { heatmapMockData } from naive-uifunction heatmapMockData(year?: recent | number): HeatmapData其实现位于 utils/index.ts不传参或传recent生成从今天起往前一年的每日数据传具体年份数字如2025生成该年 1 月 1 日至 12 月 31 日的每日数据模拟规则约 70% 的周末与 15% 的工作日为value: 0其余日期value Math.floor(Math.random() ** 2 * 40) 1偏向小值更贴近真实活跃度分布函数每次调用结果随机、不稳定仅用于演示。官方基础演示basic.demo.vue正是用它在最近一年 / 2025 / 2024 / 2023 / 2022之间切换并配合n-scrollbar做横向滚动热力图整年视图较宽建议放入x-scrollable容器。十、主题定制与样式变量与 Naive UI 其他组件一致Heatmap 支持通过n-config-provider的theme-overrides定制主题变量。可覆盖的变量定义在 light.ts包括activeColors默认[#9be9a8, #40c463, #30a14e, #216e39]、mininumColor默认取通用buttonColor2HoverrectSizeSmall/Medium/Large、borderRadiusSmall/Medium/LargexGapSmall/Medium/Large、yGapSmall/Medium/Large分别对应 small / medium / large 三档fontSizeSmall/Medium/Large、fontWeight、textColor、borderColor、loadingColorStart、loadingColorEnd。例如通过组件级主题覆盖调整格子大小与间距template n-config-provider :theme-overrides{ Heatmap: { rectSizeMedium: 14px, xGapMedium: 4px, yGapMedium: 4px } } n-heatmap :datadata / /n-config-provider /template此外组件原生支持 RTL 布局useRtl渲染--rtl类名与深色模式dark.ts样式入口见 styles/index.cssr.ts。十一、实现原理简述从数据到网格理解热力图的渲染管线有助于排查数据问题依据 Heatmap.tsx 与 utils/index.ts补全数据completeDataGaps排序数据以first-day-of-week为准向两端补齐到整周缺失日期补0周首空白按fill-calendar-leading决定补0还是null计算颜色maxValueRef求最大值calcColorByValue按value/max比例映射到颜色数组的层级定位格子createDayRect通过differenceInCalendarDays / 7计算列索引、(getDay - weekStartOn 7) % 7计算行索引组织矩阵createSparseMatrix生成 7 行稀疏矩阵每列为一周渲染render 函数输出table行内依次渲染周标签、月份标签thead与单元格tbodyvalue null的格子渲染空占位底部由footer插槽与HeatmapColorIndicator构成。结语Heatmap 是 Naive UI 中少有的数据可视化日历组件数据模型只有timestamp value两个字段配合first-day-of-week、fill-calendar-leading、加载态、5 套内置主题与 5 个插槽可以快速实现 GitHub 贡献墙、打卡日历、活跃度面板等场景。若需更细粒度的控制可继续阅读源码 Heatmap.tsx、utils/index.ts、light.ts 与测试 Heatmap.spec.tsx或参考英文版 index.demo-entry.md 获取更多示例。赞分享前端UI组件【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址https://gitcode.com/gh_mirrors/na/naive-ui点击查看免费下载相关推荐探秘React日历热力图组件React Calendar Heatmap探秘React日历热力图组件React Calendar Heatmap 在数据可视化领域中日历热力图是一个非常实用的工具它以直观的方式展现了时间序列中的Vuetify VHeatmap 组件实战指南用 v-heatmap 构建日历热力图与数据网格Vuetify VHeatmap 组件实战指南用 v heatmap 构建日历热力图与数据网格 v heatmap 是 Vuetify 实验室Labs提供前端UI组件推荐Cal-HeatMap —— 强大的日历热力图库推荐Cal HeatMap —— 强大的日历热力图库 THE 0TH POSITION OF THE ORIGINAL IMAGE 在数据可视化的世界里寻找前端UI库/组件数据分析上一篇九大网盘直链解析LinkSwift 网盘直链下载助手上手指南下一篇Spinnaker微服务版本控制确保部署一致性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Naive UI Heatmap 热力图组件完全指南：从 GitHub 风格日历到自定义主题
前端UI组件【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址https://gitcode.com/gh_mirrors/na/naive-ui点击查看免费下载热力图Heatmap组件自 Naive UI2.43.0版本开始提供用于以 GitHub 贡献墙式的周列 × 星期行网格展示时间序列数据如每日活跃度、提交次数、打卡记录。本文基于 组件文档 展开结合 核心实现 与 数据工具函数 源码系统讲解数据模型、全部 Props / Slots、内置与自定义配色、加载态以及 mock 数据用法帮助你直接在自己的 Vue 3 项目中落地一个可复制的热力图方案。一、组件概览与使用前提Heatmap 用一张日历表来展示数据每一列代表一周每一行代表星期周一到周日每个单元格是一个带颜色的方块颜色深浅映射数值大小。它在内部基于 date-fns 中按需导出可随naive-ui的 tree-shaking 机制使用template n-heatmap :datadata / /template script setup langts import { heatmapMockData } from naive-ui const data heatmapMockData(recent) /script使用前提重要官方文档明确提示颜色相关属性active-colors和minimum-color的优先级高于color-theme。如果三个属性同时设置实际生效的是active-colors与minimum-color因此文档建议不要同时设置当三者都不设置时组件使用 Naive UI 内置的类 GitHub默认配色。二、数据模型timestamp value 的结构约定data是组件的核心输入其类型定义位于 public-types.tsexport type HeatmapData HeatmapDataItem[] export interface HeatmapDataItem { timestamp: number // 时间戳毫秒 value?: number | null // 数值可选 }字段语义依据 utils/index.ts 的completeDataGaps实现timestamp毫秒级时间戳用于把每一天定位到日历网格的某个单元格。value该天的数值驱动颜色深浅。undefined或null的格子不渲染方块但保留占位缺失的日期会被自动补全为value: 0。数据会被按时间戳排序并补全首日所在周与末日所在周之间的所有空白日期确保网格完整。下面的示例直接来自 官方基础用法演示 的数据统计逻辑展示了如何基于HeatmapData计算总天数、空白天、最大值与平均值import { computed, ref } from vue import { heatmapMockData } from naive-ui const value refrecent | number(recent) const yearData computed(() heatmapMockData(value.value)) const dataStats computed(() { const data yearData.value const total data.length const zeros data.filter(d d.value 0).length const maxValue Math.max(...data.map(d d.value ?? 0)) const avgValue Math.round( (data.reduce((sum, d) sum (d.value ?? 0), 0) / total) * 100 ) / 100 return { total, zeros, maxValue, avgValue, zeroPercent: Math.round((zeros / total) * 100) } })日期对齐first-day-of-week与fill-calendar-leading网格的周从哪一天开始由first-day-of-week决定取值范围0 | 1 | 2 | 3 | 4 | 5 | 60表示周一Naive UI 的约定与 JavaScriptDate.getDay()的 0周日不同6表示周日默认值为0。源码中通过 date-picker 的工具函数 将 Naive 的语义转换为 date-fns 的weekStartsOn。测试用例 Heatmap.spec.tsx 分别验证了0 / 1 / 6三种起始日均可正常工作。fill-calendar-leading默认false控制是否填满日历网格的头部false默认数据首日之前的周内空白用value: null占位不显示方块true这些空白格子被填充为value: 0显示最浅色方块适合 GitHub 风格的最近一年整块视图。官方基础演示中正是用:fill-calendar-leadingvalue recent在最近一年模式下开启它。三、Heatmap Props 完整参考以下表格完整继承自 组件文档类型为HeatmapProps定义见 Heatmap.tsx名称类型相关类型默认值说明版本active-colorsstring[]-undefined颜色数组按从浅到深的顺序排列优先级高于color-theme2.43.0color-themegreen \| blue \| orange \| purple \| redHeatmapColorThemeundefined内置颜色主题2.43.0dataArray{ timestamp: number, value?: number \| null }HeatmapData,HeatmapDataItem[]热力图数据包含日期和数值2.43.0first-day-of-week0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6HeatmapFirstDayOfWeek0一周的开始日0表示周一6表示周日2.43.0fill-calendar-leadingboolean-false是否填满日历网格的头部适用于 GitHub 风格的最近一年视图2.43.0loadingboolean-false是否显示加载状态2.43.0loading-dataArray{ timestamp: number, value?: number \| null }HeatmapData,HeatmapDataItemundefined加载状态下展示的数据单元格value为null时不展示 cell 但占位设为任意非null值则展示加载状态2.43.0minimum-colorstring-undefined热力图最小颜色默认为active-colors中的第一个颜色2.43.0show-color-indicatorboolean-true是否显示底部的颜色层级指示器2.43.0show-month-labelsboolean-true是否显示月份标签2.43.0show-week-labelsboolean-true是否显示周标签2.43.0sizesmall \| medium \| large-medium热力图尺寸2.43.0tooltipboolean \| TooltipProps-falsetooltip 配置false为禁用对象为TooltipProps2.43.0x-gapnumber \| string-undefined水平方向间距2.43.0y-gapnumber \| string-undefined垂直方向间距2.43.0颜色合并优先级源码验证Heatmap.tsx 中的mergedColorsRef精确实现了文档所说的优先级规则const mergedMininumColor props.minimumColor || builtInMinimumColor const theme props.colorTheme heatmapColorThemes[props.colorTheme] const mergedActiveColors props.activeColors || theme || builtInActiveColors return [mergedMininumColor, ...mergedActiveColors]即minimum-color优先于主题内置最小色active-colors优先于color-themecolor-theme优先于主题默认值。最终渲染用的颜色数组是[最小色, 活跃色1, 活跃色2, ...]。颜色如何映射到数值颜色分级逻辑在 utils/index.ts 的calcColorByValue中取value / maxValue的比例上限 1按颜色数组长度分层Math.ceil(ratio * (len-1))数值 ≤ 0 或为null时一律使用第一个颜色即minimum-color。尺寸与间距的底层默认值三个尺寸对应的单元格尺寸、圆角、间距与字号在 light.ts 中定义rectSize分别为10px / 11px / 12px圆角均为2pxxGap/yGap为2px/3px。当传入x-gap、y-gap数字或 CSS 字符串均可时会通过pxfy覆盖默认值。四、内置主题与自定义颜色使用color-theme内置主题内置主题定义在 theme.ts共 5 套均为 4 级渐深色主题颜色数组浅 → 深green[#c6e48b, #7bc96f, #239a3b, #196127]blue[#c0e7ff, #73b3ff, #0969da, #0550ae]orange[#fed7aa, #fb923c, #ea580c, #c2410c]purple[#e9d5ff, #c084fc, #9333ea, #7c3aed]red[#fecaca, #f87171, #dc2626, #b91c1c]官方主题演示 的用法非常直接script setup langts import { heatmapMockData } from naive-ui const data heatmapMockData() const themes [ { name: 绿色, value: green }, { name: 蓝色, value: blue }, { name: 橙色, value: orange }, { name: 紫色, value: purple }, { name: 红色, value: red } ] as const /script template n-heatmap v-fortheme in themes :keytheme.value :datadata :color-themetheme.value / /template测试 Heatmap.spec.tsx 也对orange / blue / green等主题逐一做了挂载验证。用active-colorsminimum-color自定义颜色官方自定义颜色演示 展示了完整做法active-colors是从浅到深排列的颜色数组minimum-color单独设置最小值零值/空值的颜色。文档特别强调active-colors与minimum-color的优先级高于color-theme二者同时设置时不要再用color-theme。演示中还配合n-color-picker让用户实时改色script setup langts import { heatmapMockData } from naive-ui import { ref } from vue const data heatmapMockData() const customActiveColors ref([#9be9a8, #40c463, #30a14e, #216e39]) const minimumColor ref(#ebedf0) /script template n-heatmap :datadata :active-colorscustomActiveColors :minimum-colorminimumColor / /template五、加载状态loading / loading-dataloading与loading-data配合实现加载态其行为在源码heatmapMatrixRefHeatmap.tsx中有精确体现当loading为true且未提供loading-data时渲染一个固定的7×53 占位矩阵见createLoadingMatrix配合 animationStyle.ts 的闪烁动画展示骨架屏当同时提供loading-data时矩阵基于loading-data构建value为null的格子不展示方块但保留占位value为任意非null值则展示带加载动画的方块loading为false时忽略loading-data正常渲染data。官方基础演示中的做法是直接把yearData同时传给data和loading-data用开关切换n-heatmap :datayearData :loading-datayearData :first-day-of-weekfirstDayOfWeek :loadingloading :sizesize :show-week-labelsshowWeekLabels :show-month-labelsshowMonthLabels :show-color-indicatorshowColorIndicator :fill-calendar-leadingvalue recent /loading开关本身也在 Heatmap.spec.tsx 中被测试覆盖setProps({ loading: true })后组件正常渲染。六、标签控制月份标签、周标签与颜色指示器show-week-labels默认true左侧的星期标签。源码 Heatmap.tsx 会生成 7 个标签并按i % 2 ! 0规则只显示奇数行减少视觉噪音测试验证了开关可正确移除.n-heatmap__week-label-cell。show-month-labels默认true顶部的月份标签。源码按列上首个非空格子的月份进行分组getColsMonth并只保留覆盖周数 ≥ 3 的月份weekCount 3避免标签过挤加载态则使用固定的colSpans [5, 4, 5, 4, 5, 4, 5, 4, 4, 5, 4, 4]保持宽度一致。show-color-indicator默认true底部右侧的颜色层级指示器由 ColorIndicator.tsx 渲染从左到右展示较少 → 较多的渐变色带。七、Tooltip 配置与自定义tooltip属性接受false禁用默认或一个TooltipProps对象即 Naive UI 内置NTooltip的属性如placement、delay等。当tooltip为对象时每个格子会包一层NTooltipRect.tsx 负责具体渲染。配合#tooltip插槽可完全自定义悬浮内容插槽参数类型为HeatmapTooltipSlotProps即{ timestamp: number, value?: number | null }。官方插槽演示 给出了完整范例n-heatmap :datayearData unitactivities :tooltip{ placement: bottom, delay: 500 } template #footer n-text depth3底部显示 tooltip延迟 500ms/n-text /template template #tooltip{ timestamp: date, value: tooltipValue } 活动详情br div{{ new Date(date).toLocaleDateString() }}/div div{{ tooltipValue ?? 0 }}/div /template /n-heatmap八、插槽参考类型为HeatmapSlots定义见 public-types.ts下表完整继承自文档名称参数相关类型说明版本footer()-底部左侧信息插槽与 heatmap table 左边对齐2.43.0indicator()-底部右侧指示器插槽与 heatmap table 右边对齐2.43.0indicator-leading-text()-颜色层级指示器的前置文字2.43.0indicator-trailing-text()-颜色层级指示器的后置文字2.43.0tooltip(props: { timestamp: number, value?: number \| null })HeatmapTooltipSlotProps自定义 tooltip 内容2.43.0使用要点来自官方演示与源码 Heatmap.tsx提供indicator插槽时会完全替换内置的颜色指示器此时show-color-indicator无效indicator-leading-text/indicator-trailing-text只替换指示器两端的文字默认分别为本地化的较少/更多文案取自useLocale(Heatmap)footer与indicator分别位于底部左右两侧与表格对齐这些插槽均有对应的测试覆盖footer/indicator自定义内容的断言见 Heatmap.spec.tsx。n-heatmap :datayearData :show-color-indicatorfalse template #footer n-text depth3左侧信息插槽/n-text /template template #indicator n-text depth3右侧指示器插槽/n-text /template template #tooltip{ timestamp: date, value: tooltipValue } divstrong日期:/strong {{ new Date(date).toLocaleDateString() }}/div divstrong数值:/strong {{ tooltipValue ?? 0 }}/div div v-iftooltipValue ! null tooltipValue 5 n-tag typesuccess sizesmall高活跃度/n-tag /div /template /n-heatmap九、快速上手heatmapMockData生成模拟数据组件文档的 Others 部分给出了一个便于快速调试的导出import { heatmapMockData } from naive-uifunction heatmapMockData(year?: recent | number): HeatmapData其实现位于 utils/index.ts不传参或传recent生成从今天起往前一年的每日数据传具体年份数字如2025生成该年 1 月 1 日至 12 月 31 日的每日数据模拟规则约 70% 的周末与 15% 的工作日为value: 0其余日期value Math.floor(Math.random() ** 2 * 40) 1偏向小值更贴近真实活跃度分布函数每次调用结果随机、不稳定仅用于演示。官方基础演示basic.demo.vue正是用它在最近一年 / 2025 / 2024 / 2023 / 2022之间切换并配合n-scrollbar做横向滚动热力图整年视图较宽建议放入x-scrollable容器。十、主题定制与样式变量与 Naive UI 其他组件一致Heatmap 支持通过n-config-provider的theme-overrides定制主题变量。可覆盖的变量定义在 light.ts包括activeColors默认[#9be9a8, #40c463, #30a14e, #216e39]、mininumColor默认取通用buttonColor2HoverrectSizeSmall/Medium/Large、borderRadiusSmall/Medium/LargexGapSmall/Medium/Large、yGapSmall/Medium/Large分别对应 small / medium / large 三档fontSizeSmall/Medium/Large、fontWeight、textColor、borderColor、loadingColorStart、loadingColorEnd。例如通过组件级主题覆盖调整格子大小与间距template n-config-provider :theme-overrides{ Heatmap: { rectSizeMedium: 14px, xGapMedium: 4px, yGapMedium: 4px } } n-heatmap :datadata / /n-config-provider /template此外组件原生支持 RTL 布局useRtl渲染--rtl类名与深色模式dark.ts样式入口见 styles/index.cssr.ts。十一、实现原理简述从数据到网格理解热力图的渲染管线有助于排查数据问题依据 Heatmap.tsx 与 utils/index.ts补全数据completeDataGaps排序数据以first-day-of-week为准向两端补齐到整周缺失日期补0周首空白按fill-calendar-leading决定补0还是null计算颜色maxValueRef求最大值calcColorByValue按value/max比例映射到颜色数组的层级定位格子createDayRect通过differenceInCalendarDays / 7计算列索引、(getDay - weekStartOn 7) % 7计算行索引组织矩阵createSparseMatrix生成 7 行稀疏矩阵每列为一周渲染render 函数输出table行内依次渲染周标签、月份标签thead与单元格tbodyvalue null的格子渲染空占位底部由footer插槽与HeatmapColorIndicator构成。结语Heatmap 是 Naive UI 中少有的数据可视化日历组件数据模型只有timestamp value两个字段配合first-day-of-week、fill-calendar-leading、加载态、5 套内置主题与 5 个插槽可以快速实现 GitHub 贡献墙、打卡日历、活跃度面板等场景。若需更细粒度的控制可继续阅读源码 Heatmap.tsx、utils/index.ts、light.ts 与测试 Heatmap.spec.tsx或参考英文版 index.demo-entry.md 获取更多示例。赞分享前端UI组件【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址https://gitcode.com/gh_mirrors/na/naive-ui点击查看免费下载相关推荐探秘React日历热力图组件React Calendar Heatmap探秘React日历热力图组件React Calendar Heatmap 在数据可视化领域中日历热力图是一个非常实用的工具它以直观的方式展现了时间序列中的Vuetify VHeatmap 组件实战指南用 v-heatmap 构建日历热力图与数据网格Vuetify VHeatmap 组件实战指南用 v heatmap 构建日历热力图与数据网格 v heatmap 是 Vuetify 实验室Labs提供前端UI组件推荐Cal-HeatMap —— 强大的日历热力图库推荐Cal HeatMap —— 强大的日历热力图库 THE 0TH POSITION OF THE ORIGINAL IMAGE 在数据可视化的世界里寻找前端UI库/组件数据分析上一篇九大网盘直链解析LinkSwift 网盘直链下载助手上手指南下一篇Spinnaker微服务版本控制确保部署一致性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考