FullCalendar
일정 데이터를 날짜/시간 기준으로 배치하여 표시하는 캘린더 컴포넌트
개요
FullCalendar 컴포넌트는 Toast UI Calendar 기반으로 월/주/일 뷰를 제공합니다. 일정 카드 표시, 뷰 모드 전환, 네비게이션, 기간 선택, 드래그 앤 드롭 등 풍부한 기능을 지원합니다.
주요 특징
- ✅ 기본 상태: 일정 데이터를 날짜/시간 기준으로 배치하여 표시
- ✅ 뷰 모드 전환: 월(Month) / 주(Week) / 일(Day) 보기 전환 토글
- ✅ 월 뷰 표시: 한 화면에 한 달 기준 날짜 그리드
- ✅ 주 뷰 표시: 시간 축 기반 주 단위 그리드 + 세로 스크롤
- ✅ 일 뷰 표시: 하루의 시간 단위 일정 집중 표시
- ✅ 시간 축 표시: 주/일 뷰에서 시간 단위 세로 축
- ✅ 오늘 날짜 강조: 오늘 날짜/현재 시간 시각적 강조
- ✅ 일정 카드 표시: 카테고리별 색상 지원
- ✅ 일정 초과 처리: “더보기” UI
- ✅ 네비게이션 버튼: 이전/다음/오늘 이동 버튼
- ✅ 일정 선택: 일정 카드 클릭 시 선택 상태
- ✅ 기간 선택: 날짜/시간 셀 클릭/드래그로 기간 선택 이벤트
- ✅ 날짜 표기 현지화:
locale로 더보기 팝업 헤더 날짜 표기 지정
프로젝트팀 구현: 일정 상세 호출(Popup/Detail View)은
onEventClick핸들러를 통해 프로젝트팀이 직접 구현합니다.
뷰를 바꾸면 캘린더를 다시 만듭니다. 캘린더 엔진이 뷰마다 다른 패널 높이를 내부에 쌓아 두고 지우지 않아, 전환을 반복하면 시간 그리드가 짧아집니다. 새로 만들어 그 상태를 남기지 않습니다. 준비될 때까지 감췄다가 표시하므로 빈 화면은 보이지 않습니다.
기본 상태
일정 데이터를 날짜/시간 기준으로 배치하여 표시하는 Calendar 기본 UI를 제공합니다.
Preview
뷰 모드 전환
월(Month) / 주(Week) / 일(Day) 보기 전환 토글을 제공합니다.
Preview
월 뷰 표시
한 화면에 한 달 기준 날짜 그리드를 표시합니다.
Preview
주 뷰 표시 / 시간 축 표시
시간 축 기반의 주 단위 그리드를 표시하고 세로 스크롤을 지원합니다. 주/일 뷰에서 시간 단위를 세로 축으로 표시합니다.
Preview
일 뷰 표시
선택한 하루의 시간 단위 일정만 집중적으로 표시합니다.
Preview
오늘 날짜 강조
오늘 날짜 또는 현재 시간을 시각적으로 강조 표시합니다.
Preview
일정 카드 표시
일정 데이터를 카드 형태로 날짜 또는 시간 셀 내부에 표시합니다. 카테고리별 색상을 지정할 수 있습니다.
Preview
일정 초과 처리
일정 카드가 셀 영역을 초과하는 경우 일부 숨김 처리 후 “더보기” UI를 제공합니다. 팝업은 화면 경계를 넘지 않게 자리를 잡고, 스크롤하면 닫힙니다.
Preview
네비게이션 버튼
이전/다음 기간 이동 및 오늘 이동 버튼을 제공합니다.
Preview
일정 선택
일정 카드 클릭 시 선택 상태로 표시됩니다. onEventClick 핸들러로 선택된 일정 데이터를 전달받습니다.
Preview
기간 선택
날짜(또는 시간 셀) 클릭/드래그 시 기간 선택 이벤트를 발생시킵니다. 일정 입력 popup 호출 등에 활용합니다.
Preview
빈 칸을 클릭하거나 끌어 보세요
날짜 표기 현지화
locale은 이 컴포넌트가 직접 찍는 날짜 표기(더보기 팝업 헤더)에 쓰입니다. 미지정 시 실행 환경의 표기를 따릅니다.
Preview
시간대
timezone으로 그리드가 그려지는 시간대를 정합니다. 일정의 절대 시각은 그대로고, 화면에서 놓이는 위치만 바뀝니다. 미지정 시 실행 환경의 시간대를 씁니다.
<FullCalendar events={events} viewMode="week" timezone="America/New_York" timezoneLabel="EST" />timezoneLabel은 시간 축 왼쪽에 붙는 표기입니다. 생략하면 캘린더가 GMT 오프셋을 계산해 보여 줍니다.
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
events | CalendarEvent[] | [] | 일정 데이터 |
calendars | CalendarCategory[] | - | 캘린더 카테고리 |
restrictions | CalendarRestriction[] | [] | 제한 기간 (휴일, 마감 등) |
viewMode | "month" | "week" | "day" | "month" | 현재 뷰 모드 |
currentDate | Date | new Date() | 현재 표시 날짜 |
editable | boolean | false | 드래그 앤 드롭 활성화 |
readOnly | boolean | false | 읽기 전용 모드 |
height | string | number | 700 | 높이 |
startDayOfWeek | 0-6 | 0 | 시작 요일 (0: 일요일) |
showViewModeToggle | boolean | true | 뷰 모드 토글 표시 |
availableViewModes | CalendarViewMode[] | ["day","week","month"] | 사용 가능 뷰 모드 |
showNavigation | boolean | true | 네비게이션 버튼 표시 |
showTodayButton | boolean | true | 오늘 버튼 표시 |
monthVisibleEventCount | number | 4 | 월 뷰 셀당 최대 일정 수 |
highlightToday | boolean | true | 오늘 날짜 강조 |
showCurrentTimeLine | boolean | true | 현재 시간 라인 표시 |
weekStartTime | string | "00:00" | 주/일 뷰 시작 시간 |
weekEndTime | string | "24:00" | 주/일 뷰 종료 시간 |
locale | string | 실행 환경 표기 | 날짜 표기 (BCP-47) |
timezone | string | 실행 환경 타임존 | 그리드가 그려지는 시간대 (IANA) |
timezoneLabel | string | - | 시간 축에 붙는 표기 (예: KST) |
loading | boolean | false | 로딩 오버레이 |
className | string | - | 추가 CSS 클래스 |
Events
| Event | Type | Description |
|---|---|---|
onViewModeChange | (mode: CalendarViewMode) => void | 뷰 모드 변경 시 |
onDateChange | (date: Date) => void | 날짜 변경 시 |
onEventClick | (event: CalendarEvent) => void | 일정 클릭 시 |
onEventDoubleClick | (event: CalendarEvent) => void | 일정 더블클릭 시 |
onDateSelect | (data: CalendarDateSelectData) => void | 기간 선택 시 |
onEventChange | (data: CalendarEventChangeData) => void | 일정 드래그/크기조절 완료 시 — changes는 네이티브 Date |
onMoreClick | (date: Date, events: CalendarEvent[]) => void | 더보기 클릭 시 |
CalendarEvent
| Prop | Type | Description |
|---|---|---|
id | string | number | 고유 ID |
calendarId | string | 캘린더 카테고리 |
title | string | 일정 제목 |
start | Date | string | 시작 시간 |
end | Date | string | 종료 시간 |
isAllDay | boolean | 종일 일정 여부 |
backgroundColor | string | 배경 색상 |
기본 사용법
import {
FullCalendar,
type CalendarEvent,
type CalendarCategory,
} from "@vortex/ui-foundation"
<FullCalendar
events={events}
calendars={calendars}
viewMode="month"
height={700}
showViewModeToggle
showNavigation
highlightToday
/>접근성
권장 사항
- ✅ 키보드 네비게이션으로 날짜 이동 가능
- ✅ 일정 카드에 의미 있는 title 제공
- ❌ 색상만으로 카테고리를 구분하지 않음 (텍스트 레이블 병행)