ComponentPicker & Select
CalendarTimeline
MớiCalendarTimeline thuộc nhóm Picker & Select. Xem demo trực tiếp, cách tích hợp và các lưu ý triển khai.
Bắt đầu nhanh
Import CalendarTimeline từ entry của gói Free. Các ví dụ bên dưới thể hiện những kiểu tương tác và cấu hình được hỗ trợ.
component.tsxtsx
import { CalendarTimeline } from '@underverse-ui/underverse';Ví dụ tương tác
Dùng thử CalendarTimeline thật, xem mã ví dụ và tra cứu các prop đã được mô tả.
Đang tải ví dụ tương tác…
Tham chiếu
Tham chiếu API
Tra cứu các thuộc tính, kiểu dữ liệu được chấp nhận, giá trị mặc định và lưu ý về hành vi.
Dữ liệu được sinh từ API TypeScript công khai của thư viện. Kiểu dữ liệu, thuộc tính bắt buộc và giá trị mặc định luôn đồng bộ với mã nguồn.
CalendarTimeline
Component| Thuộc tính | Mô tả | Kiểu | Mặc định |
|---|---|---|---|
resourcesBắt buộc | Danh sách resource (các hàng). | CalendarTimelineResource<TResourceMeta>[] | Bắt buộc |
eventsBắt buộc | Danh sách event (end là exclusive). | CalendarTimelineEvent<TEventMeta>[] | Bắt buộc |
size | Preset kích thước hiển thị (sm/md/xl). | CalendarTimelineSize | "md" |
enableEventSheet | Enable the built-in right-side event details sheet on click. If `renderEventSheet` is provided, this defaults to enabled. | boolean | — |
eventSheetSize | Kích thước sheet hiển thị chi tiết event. | CalendarTimelineSheetSize | "md" |
eventSheetOverlayOpacity | Mã nguồn chưa cung cấp mô tả bổ sung. | number | — |
renderEventSheet | Hàm custom render nội dung sheet chi tiết event. | (args: { event: CalendarTimelineEvent<TEventMeta>; resource?: CalendarTimelineResource<TResourceMeta>; close: () => void; locale: string; timeZone: string; view: CalendarTimelineView; }) => React.ReactNode | — |
selectedEventId | Controlled id event đang chọn cho sheet. | string | null | — |
defaultSelectedEventId | Id event được chọn ban đầu khi uncontrolled. | string | null | — |
onSelectedEventIdChange | Gọi khi selected event id thay đổi. | (eventId: string | null) => void | — |
eventSheetOpen | Controlled trạng thái mở/đóng sheet. | boolean | — |
defaultEventSheetOpen | Trạng thái mở sheet ban đầu khi uncontrolled. | boolean | — |
onEventSheetOpenChange | Gọi khi trạng thái mở/đóng sheet thay đổi. | (open: boolean) => void | — |
onlyView | Lock the timeline to a single view and hide the view switcher. When set, `view`/`defaultView` are ignored. | CalendarTimelineView | — |
view | Active view (controlled) or allowed views list. - string: controls the current view - array: restricts which views are shown; the active view falls back to `defaultView` (if included) or the first entry. | CalendarTimelineView | CalendarTimelineView[] | — |
defaultView | Chế độ xem ban đầu khi uncontrolled. | CalendarTimelineView | "month" |
onViewChange | Gọi khi view thay đổi. | (view: CalendarTimelineView) => void | — |
dueDateSprint | Sprint view only: provide custom sprint titles (and ranges) so the header columns can display dynamic labels. If not provided, sprint headers fall back to "S01", "S02", ... | CalendarTimelineDueDateSprint | — |
date | Ngày neo cho view hiện tại (controlled). | Date | — |
defaultDate | Ngày ban đầu khi uncontrolled. | Date | — |
onDateChange | Gọi khi date thay đổi. | (date: Date) => void | — |
weekStartsOn | Ngày bắt đầu tuần (0-6). | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 1 |
locale | Locale BCP47 dùng để format header. | string | — |
timeZone | Múi giờ IANA dùng để render và tính toán. | string | — |
labels | Nhãn i18n cho UI text. | CalendarTimelineLabels | — |
formatters | Formatter tuỳ biến cho header/time/aria. | CalendarTimelineFormatters | — |
groups | Nhóm resources (tuỳ chọn). | CalendarTimelineGroup[] | — |
groupCollapsed | Map điều khiển trạng thái thu gọn group. | Record<string, boolean> | — |
defaultGroupCollapsed | Map thu gọn group mặc định khi uncontrolled. | Record<string, boolean> | — |
onGroupCollapsedChange | Gọi khi trạng thái thu gọn group thay đổi. | (next: Record<string, boolean>) => void | — |
hideResourceColumn | Hide the left resource column (resource/group labels). The grid rows still render (one per resource), but the left labels, group toggles, and UI row-resize handles are not shown. | boolean | — |
resourceColumnWidth | Controlled width of the left resource column (px or CSS width string). | number | string | — |
defaultResourceColumnWidth | Default width of the left resource column when uncontrolled (px). | number | — |
onResourceColumnWidthChange | Called when user resizes the left resource column. | (width: number) => void | — |
minResourceColumnWidth | Min width for the left resource column (px). | number | — |
maxResourceColumnWidth | Max width for the left resource column (px). | number | — |
rowHeight | Controlled height of each resource row (px). | number | — |
defaultRowHeight | Default row height when uncontrolled (px). | number | — |
onRowHeightChange | Called when user resizes row height. | (height: number) => void | — |
minRowHeight | Min row height (px). | number | — |
maxRowHeight | Max row height (px). | number | — |
rowHeights | Controlled per-resource row heights (px) keyed by resourceId. | Record<string, number> | — |
defaultRowHeights | Default per-resource row heights (px) keyed by resourceId. | Record<string, number> | — |
onRowHeightsChange | Called when per-resource row heights change. | (next: Record<string, number>) => void | — |
autoRowHeight | Auto-expand each resource row height to fit overlapping events (lanes) without collapsing into "+more". When enabled, `maxLanesPerRow` is ignored unless overridden via `autoRowHeight.maxLanesPerRow`. | boolean | { maxRowHeight?: number; maxLanesPerRow?: number } | — |
enableLayoutResize | Allow resizing layout with mouse: - column: drag the divider in the header - row: drag the bottom edge of a resource row | boolean | { column?: boolean; row?: boolean } | — |
slotMinWidth | Độ rộng tối thiểu mỗi slot (px). | number | — |
adaptiveSlotWidths | Month/day only: make slots (columns) without any events smaller to free space for slots that have events. Week view is unaffected. | CalendarTimelineAdaptiveSlotWidths | — |
dayEventStyle | Day view: visual style for events that span many time slots. - "span": event blocks span the full duration on the timeline (default) - "compact": event blocks keep a capped visual width (still positioned at correct start) | "span" | "compact" | "span" |
dayEventMaxWidth | Day view only (when `dayEventStyle="compact"`): max visual width (px). | number | — |
monthEventStyle | Month view: visual style for events that span many days. - "span": event blocks span the full duration on the timeline (default) - "compact": event blocks keep a capped visual width (still positioned at correct start) | "span" | "compact" | "span" |
monthEventMaxWidth | Month view only (when `monthEventStyle="compact"`): max visual width (px). | number | — |
overflowHidden | Clip overflow at the outer surface. Disable when child hover shadows or focus rings should escape the timeline card. Default: true. | boolean | true |
dayTimeStepMinutes | Kích thước slot ở day view (phút). | number | 60 |
enableEventTooltips | Render tooltips on events (can be expensive for large datasets). Default: true. | boolean | true |
dayHeaderMode | Day view: header rendering mode. - "full": show every time slot label (default; matches legacy behavior) - "smart": show start/…/end markers to reduce clutter on dense timelines | "full" | "smart" | "full" |
daySlotCompression | Day view: optionally compress empty time columns when `dayHeaderMode="smart"`. Default: false (keeps legacy column widths). | boolean | false |
columnVirtualization | Day view only: virtualize columns in the header/overlay when there are many time slots (e.g. 5–15min step). Keeps scroll behavior the same but reduces DOM work. | CalendarTimelineColumnVirtualization | — |
dayRangeMode | Day view horizontal range: - "full": show 24h (default) - "work": show working hours (default 08:00–17:00) | CalendarTimelineDayRangeMode | — |
workHours | Used when `dayRangeMode="work"`. Default: `{ startHour: 8, endHour: 17 }`. | { startHour: number; endHour: number } | — |
maxLanesPerRow | Số lane event tối đa trước khi gộp vào +more. | number | 3 |
now | Override thời điểm hiện tại (dùng highlight today). | Date | — |
getPortalContainer | Resolve the document element that should receive timeline dropdown portals. | () => HTMLElement | null | — |
renderResource | Render tuỳ biến ô resource (cột trái). | (resource: CalendarTimelineResource<TResourceMeta>) => React.ReactNode | — |
renderGroup | Render tuỳ biến hàng group. | (group: CalendarTimelineGroup, args: { collapsed: boolean; toggle: () => void }) => React.ReactNode | — |
renderEvent | Render tuỳ biến block event. | ( event: CalendarTimelineEvent<TEventMeta>, layout: { left: number; width: number; lane: number; height: number; timeText: string }, ) => React.ReactNode | — |
interactions | Bật create/drag/resize/delete. | CalendarTimelineInteractions | — |
onRangeChange | Gọi khi range hiển thị thay đổi. | (range: { start: Date; end: Date }) => void | — |
onEventClick | Gọi khi click event. | (event: CalendarTimelineEvent<TEventMeta>) => void | — |
onEventDoubleClick | Gọi khi double click event. | (event: CalendarTimelineEvent<TEventMeta>) => void | — |
onCreateEventClick | Custom create flow: when `interactions.creatable` + `interactions.createMode="click"`, clicking an empty cell calls this handler with the inferred range for that cell. | (args: { resourceId: string; start: Date; end: Date; slotIdx: number; view: CalendarTimelineView; locale: string; timeZone: string; }) => void | — |
onCreateEvent | Gọi khi tạo event bằng cách kéo ở ô trống. | (draft: { resourceId: string; start: Date; end: Date }) => void | — |
onEventMove | Gọi khi kéo di chuyển event. | (args: { eventId: string; resourceId: string; start: Date; end: Date }) => void | — |
onEventResize | Gọi khi resize event. | (args: { eventId: string; start: Date; end: Date }) => void | — |
onEventDelete | Gọi khi xoá event (chuột phải confirm). | (args: { eventId: string }) => void | — |
onMoreClick | Gọi khi click nút +more. | (args: { resourceId: string; hiddenEvents: CalendarTimelineEvent<TEventMeta>[] }) => void | — |
virtualization | Bật virtualization cho danh sách resource. | CalendarTimelineVirtualization | — |
Hướng dẫn sử dụng
Dùng CalendarTimeline khi lựa chọn có giới hạn nhanh và an toàn hơn nhập tự do. Cần cấu hình rõ locale, giới hạn, giá trị bị vô hiệu hóa và trạng thái xóa.
Trợ năng
Khi dùng CalendarTimeline, hãy giữ trạng thái focus dễ nhận biết, cung cấp tên truy cập khi cần và kiểm tra bàn phím cùng trình đọc màn hình trong ngữ cảnh thực tế.