Data
HeatmapCalendar
Heatmap calendario annuale stile GitHub con colonne settimane, righe giorni e intensità del colore in base a un valore numerico per giorno.
Import
import { HeatmapCalendar } from '@pzeta/vue-components'
Esempio Base
Props
| Prop | Tipo | Default | Descrizione |
|---|---|---|---|
year | number | (required) | Anno mostrato dalla heatmap (1 gennaio → 31 dicembre) |
values | HeatmapValue[] | (required) | Elenco dei valori giornalieri; ogni voce associa una data ISO YYYY-MM-DD a un valore numerico |
colorScale | string[] | ['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39'] | Scala colore dal valore più basso al più alto (min 2 valori); il primo colore rappresenta i giorni vuoti |
maxValue | number | undefined | Valore massimo per la normalizzazione; se omesso (o <= 0) si usa il valore massimo dei dati |
weekStartsOn | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 1 | Primo giorno della settimana (0 = domenica, 1 = lunedì) |
locale | string | 'it-IT' | Locale Intl.DateTimeFormat per le etichette di mesi e giorni |
showLegend | boolean | true | Mostra la legenda "meno → più" sotto la griglia |
cellSize | string | '13px' | Dimensione lato cella in CSS (es. 12px) |
HeatmapValue
| Proprietà | Tipo | Descrizione |
|---|---|---|
date | string | Data ISO YYYY-MM-DD |
value | number | Valore numerico del giorno usato per calcolare l'intensità del colore |
Emits
| Evento | Payload | Descrizione |
|---|---|---|
day-click | { date: string, value: number } | Emesso al click su una cella valorizzata; date è la data ISO della cella, value il valore associato (0 se assente). Le celle di riempimento (fuori anno) non emettono l'evento |
Esempi
Scala colore personalizzata
Sostituisci la palette stile GitHub con una tua scala colore (es. dal chiaro al blu intenso). Il primo elemento è il colore dei giorni senza valore.
Massimo fisso e settimana che inizia di domenica
maxValue fissa la soglia di normalizzazione (utile per confrontare anni diversi sulla stessa scala) e weekStartsOn: 0 mette la domenica come prima riga.
Celle compatte senza legenda
cellSize controlla la dimensione delle celle e showLegend può nascondere la legenda per integrazioni in widget ridotti.
Note Comportamento
- La griglia parte dal 1 gennaio dell'anno indicato: le celle prima del primo giorno e dopo l'ultimo vengono riempite con celle vuote (
transparent) per allineare le colonne settimanali - Il calcolo del livello di colore è
ceil((value / max) * (colorScale.length - 1)), limitato tra1e l'ultimo livello; i valori<= 0usano sempre il primo colore della scala maxValueviene ignorato se non maggiore di0: in tal caso si ricade sul massimo calcolato daivalues- I dati sono indicizzati per
datein unMapreattivo: ricostruire la reference divaluesaggiorna la heatmap in modo efficiente - Ogni cella valorizzata ha un attributo
titlenativo (YYYY-MM-DD: valore) usato come tooltip al passaggio del mouse - Le etichette dei mesi vengono mostrate solo sulla colonna che introduce un nuovo mese; le etichette dei giorni mostrano solo le righe dispari per ridurre l'affollamento
- Il contenitore ha
overflow-x: auto: su viewport stretti la heatmap scorre orizzontalmente senza collassare
TypeScript
import type {
HeatmapCalendarProps,
HeatmapValue,
HeatmapDayClickPayload,
} from '@pzeta/vue-components'
const values: HeatmapValue[] = [
{ date: '2026-01-07', value: 1 },
{ date: '2026-04-06', value: 5 },
]
const onDayClick = (payload: HeatmapDayClickPayload) => {
console.log('giorno', payload.date, 'valore', payload.value)
}
Quando usarlo
- Visualizzazione annuale "a colpo d'occhio" di attività giornaliere (assenze, presenze, ordini, contributi)
- Individuare pattern stagionali o picchi su un intero anno
- Dashboard e widget riepilogativi con densità informativa elevata
Per casi diversi:
- Overview annuale a 12 mini-mesi → YearCalendar
- Vista mese con eventi del giorno → EventCalendar
- Griglia risorsa x giorno della settimana → WeekScheduler