Events data

Events data

@mantine/schedule의 이벤트 데이터 구조와 각 콜백의 페이로드 형식을 설명하는 문서예요. start와 end는 Date 인스턴스 또는 YYYY-MM-DD HH:mm:ss 형식의 문자열(모든 Mantine 날짜 컴포넌트가 사용하는 DateTimeStringValue 타입)을 받아요.

출처: 문서

본문

ScheduleSingleEventData

반복이 없는 일회성 이벤트예요. 가장 흔한 형태예요:

import type { ScheduleSingleEventData } from '@mantine/schedule';

const event: ScheduleSingleEventData = {
  id: 'meeting-1',
  title: 'Team sync',
  start: '2024-01-15 10:00:00',
  end: '2024-01-15 11:00:00',
  color: 'blue',
};

ScheduleRecurringSeriesEventData

반복 시리즈의 원본 이벤트예요. RFC 5545 반복 규칙을 가진 recurrence 필드를 추가해요:

import type { ScheduleRecurringSeriesEventData } from '@mantine/schedule';

const series: ScheduleRecurringSeriesEventData = {
  id: 'weekly-planning',
  title: 'Weekly planning',
  start: '2024-01-15 10:00:00',
  end: '2024-01-15 11:00:00',
  color: 'blue',
  recurrence: {
    rrule: 'FREQ=WEEKLY;BYDAY=MO;COUNT=12',
    exdate: ['2024-02-12 10:00:00'],
    dtstart: '2024-01-15 10:00:00',
  },
};

recurrence 객체는 다음과 같은 모양이에요:

interface ScheduleRecurrenceData {
  /** Recurrence rule string, for example: `FREQ=WEEKLY;BYDAY=MO,WE` */
  rrule: string;

  /** Exception datetimes in `YYYY-MM-DD HH:mm:ss` or valid date string format */
  exdate?: DateTimeStringValue[];

  /** Optional explicit series start datetime */
  dtstart?: DateTimeStringValue;
}

반복 규칙과 시리즈 확장에 대한 자세한 내용은 반복 이벤트 가이드를 참고해요.

ScheduleRecurringOverrideEventData

오버라이드 이벤트는 시리즈에서 생성된 단일 발생(occurrence)을 대체해요:

import type { ScheduleRecurringOverrideEventData } from '@mantine/schedule';

const override: ScheduleRecurringOverrideEventData = {
  id: 'weekly-planning-override',
  title: 'Weekly planning (moved)',
  start: '2024-01-17 16:00:00',
  end: '2024-01-17 17:00:00',
  color: 'grape',
  recurringEventId: 'weekly-planning',
  recurrenceId: '2024-01-15 10:00:00',
};

• recurringEventId – 부모 시리즈 이벤트의 id
• recurrenceId – YYYY-MM-DD HH:mm:ss 형식의 원래 발생 날짜시간

EventPayload

payload 필드를 사용해 이벤트에 임의의 데이터를 붙일 수 있어요. payload는 라이브러리 내부에서 사용되지 않아요. 콜백(onEventClick, onEventDrop 등)과 커스텀 이벤트 렌더러(renderEventBody)에서 접근할 수 있는 애플리케이션별 데이터를 의미해요:

import type { ScheduleEventData } from '@mantine/schedule';

interface MyEventPayload {
  description: string;
  attendees: string[];
  location?: string;
}

const event: ScheduleEventData = {
  id: 'meeting-1',
  title: 'Team sync',
  start: '2024-01-15 10:00:00',
  end: '2024-01-15 11:00:00',
  color: 'blue',
  payload: {
    description: 'Weekly planning meeting',
    attendees: ['Alice', 'Bob'],
    location: 'Conference room A',
  },
};

EventPayload 자체는 그냥 Record<string, any>예요. 보통 ScheduleEventData의 제네릭 인자로 직접 만든 payload 타입을 전달해요.

반복 인스턴스 메타데이터 (Recurring instance metadata)

반복 시리즈가 표시된 날짜 범위에 대해 확장되면, 각 생성된 이벤트는 recurringInstance 메타데이터 객체를 포함해요. 이 객체는 라이브러리가 추가해요. 직접 설정하지 않아도 되지만, 콜백과 커스텀 렌더러에서 읽어 생성된 발생과 일반 이벤트를 구분할 수 있어요:

interface RecurringInstanceMeta {
  /** If true, event is generated from recurrence rule */
  isRecurringInstance: boolean;

  /** Parent series event id */
  recurringEventId: string | number;

  /** Original occurrence datetime key */
  recurrenceId: DateTimeStringValue;

  /** Original occurrence dates before any drag/drop updates */
  originalStart: DateTimeStringValue;
  originalEnd: DateTimeStringValue;
}

onEventClick에서 메타데이터를 읽는 예시예요:

<DayView
  onEventClick={(event) => {
    if (event.recurringInstance?.isRecurringInstance) {
      console.log('Clicked generated occurrence of', event.recurringInstance.recurringEventId);
    } else {
      console.log('Clicked regular event', event.id);
    }
  }}
/>

콜백 페이로드 (Callback payloads)

모든 이벤트 콜백은 사용자가 상호작용한 대상을 설명하는 구조화된 데이터를 받아요. 다음 섹션들은 각 콜백이 받는 정확한 페이로드를 문서화해요.

onEventClick

모든 뷰에서 이벤트를 클릭할 때 호출돼요:

onEventClick?: (
  event: ScheduleEventData,
  e: React.MouseEvent
) => void;

• event – 클릭한 이벤트예요. 생성된 발생이라면 recurringInstance 메타데이터를 포함해요.
• e – 네이티브 React 마우스 이벤트예요.

onEventDrop

드래그 후 이벤트를 드롭할 때 호출돼요(withEventsDragAndDrop 필요):

onEventDrop?: (data: {
  eventId: string | number;
  newStart: DateTimeStringValue;
  newEnd: DateTimeStringValue;
  event: ScheduleEventData;
}) => void;

• eventId – 드롭된 이벤트의 id (event.id와 동일)예요. 생성된 반복 인스턴스의 경우 합성된 발생 id(<seriesId>::<recurrenceId>)이며 시리즈 id가 아니에요. 발생을 처리할 때 부모 시리즈 id를 얻으려면 event.recurringInstance?.recurringEventId를 사용해요.
• newStart / newEnd – YYYY-MM-DD HH:mm:ss 형식의 새 날짜시간 값이에요.
• event – 해당 시점에 recurringInstance 메타데이터를 포함한 전체 이벤트 데이터예요.

onEventResize

이벤트를 위나 아래 가장자리를 끌어 리사이즈할 때 호출돼요(withEventResize 필요):

onEventResize?: (data: {
  eventId: string | number;
  newStart: DateTimeStringValue;
  newEnd: DateTimeStringValue;
  event: ScheduleEventData;
}) => void;

페이로드는 생성된 반복 인스턴스의 eventId에 대한 주의사항을 포함해 onEventDrop과 동일한 모양이에요.

onEventDragStart / onEventDragEnd

이벤트 드래그가 시작되거나 끝날 때 호출돼요:

onEventDragStart?: (event: ScheduleEventData) => void;
onEventDragEnd?: () => void;

onEventDragEnd는 성공적인 드롭과 취소된 드래그 모두에서 호출돼요. 새 위치가 필요하면 onEventDrop을 사용해요.

onTimeSlotClick

DayView 또는 WeekView에서 타임 슬롯을 클릭할 때 호출돼요:

onTimeSlotClick?: (data: {
  slotStart: DateTimeStringValue;
  slotEnd: DateTimeStringValue;
  nativeEvent: React.MouseEvent;
}) => void;

• slotStart / slotEnd – YYYY-MM-DD HH:mm:ss 형식의 슬롯 범위예요. 슬롯 길이는 뷰의 intervalMinutes prop이 제어해요.

onAllDaySlotClick

DayView 또는 WeekView에서 종일 슬롯을 클릭할 때 호출돼요:

onAllDaySlotClick?: (
  date: DateStringValue,
  event: React.MouseEvent
) => void;

• date – YYYY-MM-DD 형식의 클릭한 날짜예요.

onDayClick

MonthView 또는 YearView에서 날짜를 클릭할 때 호출돼요:

onDayClick?: (
  date: DateStringValue,
  event: React.MouseEvent
) => void;

• date – YYYY-MM-DD 형식의 클릭한 날짜예요.

onSlotDragEnd

타임 슬롯이나 날짜 셀을 가로질러 드래그해 슬롯 범위를 선택할 때 호출돼요(withDragSlotSelect 필요):

onSlotDragEnd?: (
  rangeStart: DateTimeStringValue,
  rangeEnd: DateTimeStringValue
) => void;

• rangeStart / rangeEnd – YYYY-MM-DD HH:mm:ss 형식의 선택한 범위예요.

onExternalEventDrop

일정 바깥에서 항목을 끌어 슬롯에 드롭할 때 호출돼요:

onExternalEventDrop?: (
  dataTransfer: DataTransfer,
  dropDateTime: DateTimeStringValue
) => void;

• dataTransfer – 외부 항목이 onDragStart 핸들러 중 설정한 네이티브 DataTransfer 객체예요. dataTransfer.getData(type)로 커스텀 데이터를 읽어요.
• dropDateTime – YYYY-MM-DD HH:mm:ss 형식의 드롭 대상 날짜시간이에요.

canDragEvent / canResizeEvent

권한 콜백이에요. 특정 이벤트의 드래그나 리사이즈를 막으려면 false를 반환해요:

canDragEvent?: (event: ScheduleEventData) => boolean;
canResizeEvent?: (event: ScheduleEventData) => boolean;

날짜 및 시간 값 형식 (Date and time value formats)

이벤트 데이터와 콜백 페이로드는 다음 문자열 형식을 일관되게 사용해요:

• DateStringValue – YYYY-MM-DD (예: 2024-01-15)
• DateTimeStringValue – YYYY-MM-DD HH:mm:ss (예: 2024-01-15 10:00:00)

이 타입들은 @mantine/dates와 @mantine/schedule에서 공유되며 두 패키지 모두에서 내보내져요.

더 알아보기 (Learn more)

• Recurring events
• CodeHighlight