Ordo UI
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*number91—
className*string——
emptyLabel*string——
formatTip*(count: number) => string——
labels*Partial<ActivityHeatmapLabels>——

源码

packages/patterns/src/components/activity-heatmap.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

活动热力图:日期+计数数组渲染周列格场,days 控制窗口;无数据时显示 emptyLabel,tooltip 文案可覆写。