PatternsData Display
ActivityHeatmap
@mox-hub/patterns 模式 · Data Display · canonical
activity-heatmap@mox-hub/patternsData Displaycanonicalsrc/components/activity-heatmap.tsx变体演示activity-heatmap
10月11月
少多
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| data* | { date: string; count: number; }[] | — | — |
| days* | number | 91 | — |
| className* | string | — | — |
| emptyLabel* | string | — | — |
| formatTip* | (count: number) => string | — | — |
| labels* | Partial<ActivityHeatmapLabels> | — | — |
源码
import * as React from 'react'
import { cn } from '@mox-hub/ui'
import { Tooltip, TooltipContent, TooltipTrigger } from '@mox-hub/ui/components/tooltip'
import { useFormatters } from '@mox-hub/ui/i18n'
import { usePatternLabels } from '../lib/i18n'
export interface ActivityHeatmapLabels {
empty: string
less: string
more: string
activity: (count: number) => string
}
const DEFAULT_LABELS: ActivityHeatmapLabels = {
empty: '暂无活动',
less: '少',
more: '多',
activity: (count) => `${count} 次活动`,
}
export interface ActivityHeatmapProps {
/** 稀疏日序列:[{date: 'YYYY-MM-DD', count}] */
data: Array<{ date: string; count: number }>
/** 渲染天数(从今天往回);年视图传 365 */
days?: number
className?: string
emptyLabel?: string
/** 格子悬浮浮窗文案(count 原值);缺省为「N 次活动」 */
formatTip?: (count: number) => string
labels?: Partial<ActivityHeatmapLabels>
}
const LEVEL_CLASS = [
'bg-muted',
'bg-accent-green/25',
'bg-accent-green/45',
'bg-accent-green/70',
'bg-accent-green',
]
function levelOf(count: number, max: number): number {
if (count <= 0) return 0
if (max <= 1) return 4
const ratio = count / max
if (ratio > 0.75) return 4
if (ratio > 0.5) return 3
if (ratio > 0.25) return 2
return 1
}
/**
* 活跃热力图(GitHub 风格,纯 CSS grid,无第三方依赖)。
* 列 = 周,行 = 周一~周日;输入稀疏序列自动补零;
* 每格 hover 弹 Tooltip 浮窗(日期 + 用量),网格下方带月份刻度。
*/
export function ActivityHeatmap({
data,
days = 91,
className,
emptyLabel,
formatTip,
labels,
}: ActivityHeatmapProps) {
const D = usePatternLabels('activityHeatmap', DEFAULT_LABELS)
const F = useFormatters()
const L = { ...D, ...labels }
const resolvedEmpty = emptyLabel ?? L.empty
const byDate = React.useMemo(() => {
const map = new Map<string, number>()
for (const d of data) map.set(d.date, d.count)
return map
}, [data])
const cells = React.useMemo(() => {
// 对齐到周一开头
const today = new Date()
const end = new Date(today)
end.setDate(end.getDate() + (7 - ((end.getDay() + 6) % 7) + 1) % 7 || 7 - 1)
const start = new Date(end)
start.setDate(start.getDate() - (Math.ceil(days / 7) * 7 - 1))
const list: Array<{ date: string; count: number; future: boolean }> = []
for (let d = new Date(start); d <= end; d.setDate(d.getDate() + 1)) {
const key = d.toISOString().slice(0, 10)
list.push({
date: key,
count: byDate.get(key) ?? 0,
future: d.getTime() > today.getTime(),
})
}
return list
}, [byDate, days])
const max = Math.max(1, ...cells.map((c) => c.count))
const weeks: Array<Array<{ date: string; count: number; future: boolean }>> = []
for (let i = 0; i < cells.length; i += 7) {
weeks.push(cells.slice(i, i + 7))
}
// 月份刻度:每周取列首(周一)判定,1~7 日所在列为该月首列;相邻月去重
const monthTicks = (() => {
const ticks = new Map<number, string>()
let lastMonth = -1
for (let wi = 0; wi < weeks.length; wi++) {
const first = weeks[wi][0]
if (!first || first.future) continue
const d = new Date(first.date)
if (Number.isNaN(d.getTime())) continue
if (d.getDate() <= 7 && d.getMonth() !== lastMonth) {
ticks.set(wi, F.date(d, { month: 'short' }))
lastMonth = d.getMonth()
}
}
return ticks
})()
const hasData = cells.some((c) => c.count > 0)
return (
<div data-slot="activity-heatmap" className={cn('space-y-1.5', className)}>
{hasData ? (
<>
<div className="flex gap-0.5 overflow-x-auto pb-1">
{weeks.map((week, wi) => (
<div key={wi} className="flex flex-col gap-0.5">
{week.map((cell) =>
cell.future ? (
<div key={cell.date} className="size-3 rounded-xs bg-transparent" />
) : (
<Tooltip key={cell.date}>
<TooltipTrigger
render={
<div
className={cn(
'size-3 rounded-xs',
LEVEL_CLASS[levelOf(cell.count, max)],
)}
/>
}
/>
<TooltipContent side="top" className="text-xs">
<p className="font-medium">{cell.date}</p>
<p className="text-muted-foreground">
{formatTip ? formatTip(cell.count) : L.activity(cell.count)}
</p>
</TooltipContent>
</Tooltip>
),
)}
</div>
))}
</div>
<div className="flex gap-0.5">
{weeks.map((week, wi) => (
<span
key={wi}
className="w-3 shrink-0 text-3xs leading-relaxed text-muted-foreground"
>
{monthTicks.get(wi) ?? ''}
</span>
))}
</div>
</>
) : (
<p className="text-xs text-muted-foreground">{resolvedEmpty}</p>
)}
<div className="flex items-center gap-1 text-3xs text-muted-foreground">
<span>{L.less}</span>
{LEVEL_CLASS.map((cls, i) => (
<span key={i} className={cn('size-2.5 rounded-xs', cls)} />
))}
<span>{L.more}</span>
</div>
</div>
)
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
活动热力图:日期+计数数组渲染周列格场,days 控制窗口;无数据时显示 emptyLabel,tooltip 文案可覆写。