useCalendarApp 레퍼런스

useCalendarApp(config: CalendarAppConfig)은 DayFlow 코어를 애플리케이션과 연결해 주는 훅입니다. 설정 객체 하나를 전달해 뷰를 등록하고, 초기 이벤트를 넣고, 선택적 UI를 켜고, 생명주기 콜백을 연결합니다. 이 문서에서는 사용할 수 있는 모든 옵션을 살펴봅니다.

빠른 시작

import {
  useCalendarApp,
  DayFlowCalendar,
  createMonthView,
  createWeekView,
  ViewType,
} from '@dayflow/react';
import '@dayflow/core/dist/styles.css';

export function TeamCalendar() {
  const calendar = useCalendarApp({
    views: [createMonthView(), createWeekView()],
    defaultView: ViewType.MONTH,
    initialDate: new Date(),
    events: [],
  });

  return <DayFlowCalendar calendar={calendar} />;
}

<template>
  <DayFlowCalendar :calendar="calendar" />
</template>

<script setup>
import { DayFlowCalendar, useCalendarApp } from '@dayflow/vue';
import { createMonthView, createWeekView, ViewType } from '@dayflow/core';
import '@dayflow/core/dist/styles.css';

const calendar = useCalendarApp({
  views: [createMonthView(), createWeekView()],
  defaultView: ViewType.MONTH,
  initialDate: new Date(),
  events: [],
});
</script>

import { Component } from '@angular/core';
import { createMonthView, createWeekView, ViewType } from '@dayflow/core';
import { DayFlowCalendarModule } from '@dayflow/angular';
import '@dayflow/core/dist/styles.css';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DayFlowCalendarModule],
  template: `
    <dayflow-calendar [calendar]="calendar"></dayflow-calendar>
  `
})
export class AppComponent {
  calendar = {
    views: [createMonthView(), createWeekView()],
    defaultView: ViewType.MONTH,
    initialDate: new Date(),
    events: [],
  };
}

<script>
  import { DayFlowCalendar, useCalendarApp } from '@dayflow/svelte';
  import { createMonthView, createWeekView, ViewType } from '@dayflow/core';
  import '@dayflow/core/dist/styles.css';

  const calendar = useCalendarApp({
    views: [createMonthView(), createWeekView()],
    defaultView: ViewType.MONTH,
    initialDate: new Date(),
    events: [],
  });
</script>

<DayFlowCalendar {calendar} />

설정 한눈에 보기

주요 옵션

Views (필수)

• 각 뷰는 { type, component, config } 형태의 CalendarView 객체입니다.
• DayFlow는 바로 사용할 수 있는 정의를 반환하는 팩토리(createDayView, createWeekView, createMonthView, createAgendaView, createYearView)를 제공합니다.
• defaultView는 등록된 뷰 타입 중 하나와 일치해야 합니다. 그렇지 않으면 초기화 과정에서 오류가 발생합니다.

Events

• 전달한 배열이 메모리상의 CalendarApp.state.events 목록이 됩니다.
• useCalendarApp은 앱의 변경을 감시하므로 calendar.addEvent()나 calendar.updateEvent()를 호출하면 애플리케이션 상태가 자동으로 동기화됩니다.
• 이벤트가 Event 인터페이스를 따르는지 확인하세요(start/end는 PlainDate, PlainDateTime, ZonedDateTime을 받습니다).

Plugins

• 플러그인은 { name, install(app), config } 형태이며 생성 시 한 번만 실행됩니다.
• 플러그인으로 드래그 핸들러, 키보드 단축키, 분석 옵저버를 등록하거나 app.getPlugin(name)으로 자체 API를 노출할 수 있습니다.

Callbacks

callbacks는 상태를 백엔드나 분석 계층과 동기화된 상태로 유지해 줍니다:

• onViewChange(view)는 뷰 전환이 성공한 뒤에 호출됩니다.
• onDateChange(date)는 포커스된 날짜가 바뀔 때마다 호출됩니다(이동 또는 선택).
• onVisibleRangeChange(start, end, reason)은 표시 중인 날짜 범위가 바뀔 때 호출됩니다. 별도 계산 없이 더 정확한 범위로 데이터를 가져올 수 있습니다.
• onEventCreate(event), onEventUpdate(event), onEventDelete(id)는 CRUD 작업에 대응합니다. API 동기화에 적합합니다.
• onEventDoubleClick(event, e)는 기본 모드인 eventDetailTrigger: 'dbClick'에서 이벤트를 더블 클릭할 때 호출됩니다. 외부 팝오버의 기준점으로 e.currentTarget을 사용하고, DayFlow 기본 상세 패널·대화상자를 막으려면 false를 반환하세요.
• onMoreEventsClick(date)는 월 뷰에서 "+ X개 더" 링크를 클릭할 때 호출됩니다.
• onCalendarCreate(calendar), onCalendarUpdate(calendar), onCalendarDelete(id)는 캘린더 CRUD 작업에 대응합니다.
• onCalendarMerge(sourceId, targetId)는 두 캘린더를 병합할 때 호출됩니다(예: "업무"를 "개인"에 합치는 경우).
• onRender()는 캘린더가 렌더링을 한 차례 마쳤을 때 실행됩니다(계측에 유용합니다).

defaultView와 initialDate

• defaultView는 초기 state.currentView를 정합니다. 지정하지 않으면 DayFlow가 ViewType.WEEK로 되돌아가므로, 뷰가 하나뿐인 캘린더에서는 명시적으로 지정하세요.
• initialDate는 state.currentDate와 내부 visibleMonth를 함께 초기화합니다. 라우팅이나 사용자 설정에서 날짜를 가져온다면 이 값을 바꾸세요.

timeZone

• timeZone은 일·주·월·아젠다·연간 뷰의 기본 표시 및 편집 시간대를 정합니다.
• 지정하지 않으면 DayFlow가 사용자의 시스템 시간대에서 값을 가져옵니다.
• timeZone을 바꾸면 UI가 다시 계산되어 표시되지만, 그 자체로 이벤트 데이터가 바뀌지는 않습니다.
• 변경이 적용된 뒤에도 편집 콜백은 정규화된 이벤트 데이터를 반환합니다. DayFlow는 임시 표시용 시간대를 저장 형태로 남기지 않습니다.
• 일·주 뷰의 secondaryTimeZone은 표시 전용 참조 축일 뿐이며, 앱의 기본 시간대를 대체하지 않습니다.

switcherMode

• 'buttons': 가로 버튼 그룹으로 표시합니다. 데스크톱에 적합합니다.
• 'select': 드롭다운으로 표시합니다. 공간이 부족하거나 뷰 타입이 많을 때 유용합니다.

calendars와 defaultCalendar

• calendars는 각 캘린더 타입(id, name, colors, 표시 여부)을 정의합니다. 캘린더 레지스트리가 theme.mode('light' | 'dark' | 'auto')에 따라 밝은 색상과 어두운 색상을 자동으로 선택합니다.
• defaultCalendar는 새 이벤트가 어떤 캘린더를 상속할지 정합니다. 지정하지 않으면 처음 표시되는 캘린더가 사용됩니다.

CalendarType의 속성:

CalendarColors의 속성:

theme

theme 설정은 캘린더 전체의 시각적 외형을 제어합니다:

const calendar = useCalendarApp({
  theme: {
    mode: 'dark', // 'light' | 'dark' | 'auto'
  },
});

테마 모드:

• 'light': 밝은 배경과 어두운 글자를 사용하는 라이트 모드(기본값)
• 'dark': 어두운 배경과 밝은 글자를 사용하는 다크 모드
• 'auto': 시스템 테마 설정을 자동으로 따릅니다

코드로 테마 바꾸기:

// Get current theme
const currentTheme = calendar.app.getTheme();

// Set theme
calendar.app.setTheme('dark');

// Subscribe to theme changes
calendar.app.subscribeThemeChange(theme => {
  console.log('Theme changed to:', theme);
});

다크 모드 색상 직접 지정하기:

캘린더 타입마다 라이트 모드와 다크 모드에 서로 다른 색상을 지정할 수 있습니다:

const calendars = [
  {
    id: 'work',
    name: 'Work',
    colors: {
      // Light mode colors
      lineColor: '#0066cc',
      eventColor: '#e6f2ff',
      eventSelectedColor: '#cce4ff',
      textColor: '#003d7a',
    },
    darkColors: {
      // Dark mode colors
      lineColor: '#4da6ff',
      eventColor: '#1a3d5c',
      eventSelectedColor: '#2a5a8a',
      textColor: '#b3d9ff',
    },
  },
];

테마에 대한 전체 문서는 다크 모드를 참고하세요.

locale

locale 옵션은 캘린더의 언어와 지역 설정을 지정합니다.

• 문자열: 'en-US', 'ja', 'zh', 'de', 'fr', 'es', 'ko' 같은 언어 코드를 사용합니다.
• Locale 객체: 타입 안전성을 위해 가져온 Locale 객체를 전달하거나, 지원되지 않는 언어라면 직접 만든 객체를 전달합니다.

// String code
const calendar = useCalendarApp({
  locale: 'ja',
});

// Additional Locale object from the localization plugin
import { ja } from '@dayflow/plugin-localization';
const calendar = useCalendarApp({
  locale: ja,
});

// Custom Locale object
const customLocale = {
  code: 'it',
  messages: { today: 'Oggi', ... }
};
const calendar = useCalendarApp({
  locale: customLocale,
});

useEventDetailDialog

• true로 설정하면 기본 모달 대화상자(DefaultEventDetailDialog)가 켜집니다.
• DayFlowCalendar의 eventDetailContent나 eventDetailDialog와 함께 사용하면 코어의 상태 관리는 그대로 두고 UI만 교체할 수 있습니다.

eventDetailTrigger

• 'dbClick'(기본값): 한 번 클릭하면 이벤트가 선택되고, 더블 클릭하면 상세 패널·대화상자가 열립니다.
• 'click': 한 번 클릭하면 상세 패널·대화상자가 바로 열립니다.
• 터치 입력은 이 옵션과 무관하게 동일합니다. 이벤트를 탭하면 상세가 열립니다.

const calendar = useCalendarApp({
  views: [createMonthView()],
  eventDetailTrigger: 'click',
});

useCalendarHeader

• true(기본값): 내장 캘린더 헤더를 렌더링합니다.
• false: 헤더를 완전히 숨깁니다.

직접 만든 헤더를 렌더링하려면 DayFlowCalendar의 calendarHeader 슬롯을 사용하세요. 자세한 내용은 캘린더 헤더를 참고하세요.

readOnly

• true: 내장 편집 UI(드래그, 생성, 편집)를 비활성화합니다.
• ReadOnlyConfig: 세부적으로 제어합니다.
  • draggable: 드래그 허용 여부입니다.
  • viewable: 이벤트 상세를 열 수 있는지 여부입니다.
• calendar.addEvent(), calendar.updateEvent(), calendar.deleteEvent(), calendar.applyEventsChanges() 같은 코드 기반 API는 읽기 전용 모드에서도 그대로 동작합니다.
• 직접 만든 UI에서는 calendar.canMutateFromUI()로 생성·편집·삭제 컨트롤을 표시할지 판단하세요.
• 자세한 내용은 읽기 전용 모드를 참고하세요.

allDaySortComparator

모든 뷰(일, 주, 월, 아젠다, 연)에서 종일 이벤트 행의 정렬 순서를 제어합니다.

기본적으로 DayFlow는 다음과 같이 동작합니다:

• 종일 이벤트를 처음 등장한 순서대로 calendarId 기준으로 묶습니다
• 여러 날에 걸친 종일 이벤트를 하루짜리 종일 이벤트보다 위에 둡니다
• 같은 캘린더의 종일 이벤트를 시각적으로 모아 둡니다

최종 순서를 완전히 직접 정하고 싶을 때만 allDaySortComparator를 전달하세요. 지정하면 비교 함수의 결과가 그대로 사용됩니다.

비교 함수를 전달하면 정렬을 완전히 제어할 수 있습니다. 두 개의 Event 객체를 받으며 JavaScript의 Array.sort와 동일하게 동작합니다:

const calendar = useCalendarApp({
  allDaySortComparator: (a, b) => a.title.localeCompare(b.title),
});

@dayflow/core에서 내보내는 헬퍼 함수:

import { sortAllDayByTitle } from '@dayflow/core';

const calendar = useCalendarApp({
  allDaySortComparator: sortAllDayByTitle,
});

런타임에 정렬을 바꾸려면 updateConfig를 사용하세요:

calendar.app.updateConfig({ allDaySortComparator: sortAllDayByTitle });

// Restore the default calendar-grouped ordering
calendar.app.updateConfig({ allDaySortComparator: undefined });

고급 설정 예시

import {
  useCalendarApp,
  DayFlowCalendar,
  createMonthView,
  createWeekView,
  ViewType,
} from '@dayflow/react'; // or '@dayflow/vue', '@dayflow/svelte', '@dayflow/angular'
import { createSidebarPlugin } from '@dayflow/plugin-sidebar';
import '@dayflow/core/dist/styles.css';

const calendars = [
  {
    id: 'work',
    name: 'Work',
    colors: {
      eventColor: '#2563eb',
      eventSelectedColor: '#1d4ed8',
      lineColor: '#1e40af',
      textColor: '#ffffff',
    },
  },
  {
    id: 'personal',
    name: 'Personal',
    colors: {
      eventColor: '#f97316',
      eventSelectedColor: '#ea580c',
      lineColor: '#c2410c',
      textColor: '#ffffff',
    },
  },
];

export function AdvancedCalendar() {
  const calendar = useCalendarApp({
    views: [createMonthView(), createWeekView()],
    defaultView: ViewType.WEEK,
    initialDate: new Date('2024-10-01'),
    events: [],
    calendars,
    defaultCalendar: 'work',
    switcherMode: 'select',
    callbacks: {
      onEventUpdate: event => api.events.update(event),
      onVisibleRangeChange: (start, end, reason) =>
        preloadVisibleRange(start, end, reason),
    },
    plugins: [
      createSidebarPlugin({
        width: 280,
        initialCollapsed: false,
      }),
    ],
    useEventDetailDialog: true,
  });

  return <DayFlowCalendar calendar={calendar} />;
}

팁: useCalendarApp이 반환하는 객체는 상태(currentView, currentDate, events)와 동작을 모두 제공합니다. 같은 인스턴스를 DayFlowCalendar, 직접 만든 툴바, 사이드 패널과 공유하면 모든 것이 동기화된 상태로 유지됩니다.