事件區段時間軸｜免費 React 元件

甘特感的事件區段圖 React 元件：多條泳道上的時間區段條，拖曳或方向鍵平移瀏覽，hover 或聚焦展開事件卡，自包含 SVG 刻度並附螢幕閱讀器資料表。

排程、發版計畫、專案里程碑這類「誰在什麼時候做什麼」的資料最適合用它呈現。左側是固定的泳道標籤欄，右側是可平移的時間畫布：頂部刻度依可視天數自動切換日／週／月（例如「10 月 3 日」），每個事件畫成依起訖日定位的圓角長條，寬度不夠時只留色條不顯示文字。按住畫布拖曳即可平移，放手帶慣性滑行；Shift＋滾輪或觸控板水平捲動也能平移，右上與左上的箭頭鈕一次移動三分之一畫面。滑過或聚焦事件條會浮起並展開事件卡（起訖日期、天數、狀態與說明），點擊後卡片釘住，再點一次或按 Esc 關閉。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add event-bar-chart

還沒有專案，或安裝遇到問題？看快速開始 →

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

可視天數visibleSpan

泳道高度（px）laneHeight

顯示今天線showToday

事件卡展開時長（ms）duration

180

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<EventBarChart/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

安裝

npx webberui@latest add https://webberui.com/r/event-bar-chart.json

或在 components.json 設定 registries 後，改用 @webberui/event-bar-chart 安裝。

使用

import { EventBarChart } from "@/components/ui/event-bar-chart";

<EventBarChart
  lanes={[
    { id: "design", label: "設計" },
    { id: "web", label: "前端", color: "#3b82f6" },
  ]}
  events={[
    {
      id: "d1",
      lane: "design",
      start: "2026-10-03",
      end: "2026-10-18",
      label: "設計稿審查",
      status: "active",
      detail: "首頁與結帳流程的高保真稿。",
    },
    { id: "w1", lane: "web", start: "2026-10-12", end: "2026-10-30", label: "結帳流程改版", status: "planned" },
  ]}
  visibleSpan={30}
  onSelectedChange={(id) => console.log(id)}
/>

Props

Prop	型別	預設值	說明
`lanes`	`EventBarLane[]`	—	泳道清單，由上而下排列
`events`	`EventBarEvent[]`	—	事件清單；Tab 順序依開始時間排序，與陣列順序無關
`domain`	`EventBarDomain`	事件範圍加 5% 邊	可瀏覽的時間範圍，平移值夾在其中
`visibleSpan`	`number`	`30`	一個畫面可見的天數；範圍比它短時整段塞滿
`selectedId`	`string \| null`	—	受控的選取（釘住卡片）事件 id；未提供時由元件內部管理
`defaultSelectedId`	`string \| null`	`null`	非受控模式的初始選取事件
`onSelectedChange`	`(id: string \| null) => void`	—	選取變動時回呼；再點一次、按 Esc 或關閉鈕回傳 `null`
`today`	`string \| number \| null`	使用者本地日期	「今天」的日期；未提供時於掛載後讀取，傳 `null` 等同不顯示
`showToday`	`boolean`	`true`	是否顯示「今天」垂直指示線
`laneHeight`	`number`	`40`	每條泳道的高度（px）
`ariaLabel`	`string`	`"事件區段時間軸"`	圖表的無障礙名稱，用於摘要與資料表標題
`className`	`string`	—	透傳到最外層容器

EventBarLane

欄位	型別	預設值	說明
`id`	`string`	—	唯一識別碼，事件以 `lane` 欄位對應
`label`	`string`	—	泳道名稱
`color`	`string`	強調色變數	此泳道的事件條顏色（任何合法 CSS 色值）

EventBarEvent

欄位	型別	預設值	說明
`id`	`string`	—	唯一識別碼
`lane`	`string`	—	所屬泳道 id；找不到對應泳道的事件不會畫出
`start`	`string \| number`	—	開始日：ISO 日期字串或毫秒時間戳
`end`	`string \| number`	—	結束日（含當天）
`label`	`string`	—	事件名稱，顯示於條內與事件卡標題
`detail`	`string`	—	事件卡內的補充說明
`status`	`"done" \| "active" \| "planned"`	—	狀態：已完成（淡色加左側色邊）、進行中（實色）、規劃中（虛線框）

EventBarDomain

欄位	型別	預設值	說明
`start`	`string \| number`	—	可瀏覽範圍的第一天
`end`	`string \| number`	—	可瀏覽範圍的最後一天（含當天）

另外具名匯出 formatEventRange(start, end)，回傳「10/3–10/18 · 16 天」格式的字串，方便在圖表外的讀數沿用同一套格式。

細節

日期一律以 UTC 日曆日解讀：ISO 日期字串被瀏覽器當成 UTC，若改用本地時區取月日，伺服器與台灣使用者會算出不同結果；因此 end 是含當天的結束日，條的右端畫到隔天 0 點。
刻度：可視 14 天以內用日刻度、70 天以內用週刻度（落在週一）、更長用月刻度；再依每天的像素寬度拉大間隔，避免標籤擠在一起。
初始畫面讓「今天」落在可視寬的左三分之一；今天不在範圍內就從頭開始。鍵盤聚焦到畫面外的事件條時會自動平移過去，滑鼠點擊則不會跳動。
拖曳位移超過 4px 才算拖曳，此時才捕捉指標，所以輕點事件條仍是正常點擊；拖曳放手後依釋放速度做慣性滑行（power 0.6），撞到邊界會輕微回彈。
強調色走 --wb-event-bar-chart-accent 變數（預設淺色 #0d9488、深色 #2dd4bf），未設定 color 的泳道都用它；事件卡展開時長走 --wb-event-bar-chart-duration（預設 180ms）。
同一泳道內時間重疊的事件會互相疊在一起，需要的話請拆成兩條泳道。

可及性

時間畫布可聚焦（role="group"），←／→ 平移、Home 回到今天、End 跳到最後；SVG 刻度為 role="img"，aria-label 摘要泳道數、事件數與範圍，另以 aria-describedby 指向一份 sr-only 資料表
每個事件條是原生 button，Tab 依時間順序移動，aria-label 例如「設計稿審查，10 月 3 日至 10 月 18 日，進行中」，aria-pressed 反映是否釘住
事件卡在 hover／聚焦時為 role="tooltip"，釘住後改為 role="dialog" 並附關閉鈕，Esc 可關閉
使用者系統開啟「減少動態效果」時，事件條直接完整顯示、不播放生長動畫，平移改為瞬間跳轉、沒有慣性與彈簧，事件卡只做淡入

事件區段時間軸

把這個效果裝進你的專案

本頁目錄