useCalendarApp

useCalendarApp(config: CalendarAppConfig) は DayFlow の中枢フックです。ビューの登録、イベントやカレンダータイプの投入、テーマ設定、コールバック登録などを 1 つのオブジェクトで完結させます。

クイックスタート

import {
  useCalendarApp,
  DayFlowCalendar,
  createMonthView,
  createWeekView,
  ViewType,
} from '@dayflow/react'; // or '@dayflow/vue', '@dayflow/svelte', '@dayflow/angular'
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} />;
}

主な設定項目

オプション型必須デフォルト説明
viewsCalendarView[]必須—表示するビューを登録。createMonthView() などのファクトリを使用。
pluginsCalendarPlugin[]任意[]ドラッグ操作やショートカットなどのプラグインをインストール。
eventsEvent[]任意[]初期イベント配列。以後は calendar.addEvent などで更新。
callbacksCalendarCallbacks任意{}ビュー変更やイベント CRUD をフックするライフサイクルコールバック。
defaultViewViewType任意ViewType.WEEK最初に表示するビュー。views に含まれている必要あり。
initialDateDate任意new Date()フォーカスする基準日。ルーティングの状態などから差し替え可能。
timeZonestring任意ユーザーのシステムタイムゾーン全ビュー共通の表示 / 編集タイムゾーン。
switcherMode'buttons' | 'select'任意'buttons'ビルトインビュースイッチャーの表示方法。
calendarsCalendarType[]任意[]カテゴリや色の定義。calendarId と連携。
defaultCalendarstring任意最初の可視カレンダー新規イベント作成時の既定カレンダー ID。
themeThemeConfig任意{ mode: 'light' }テーマモード（light/dark/auto）やトークン上書き。
localestring | Locale任意'en-US'国際化（i18n）のためのロケール設定。言語コード（'ja'など）またはLocaleオブジェクト。
useEventDetailDialogboolean任意false詳細表示をモーダルダイアログに切り替える。
useCalendarHeaderboolean任意trueデフォルトヘッダーの有効化（true）または非表示（false）。カスタムヘッダーは DayFlowCalendar の calendarHeader スロットを使用します。
readOnlyboolean | ReadOnlyConfig任意false組み込みの変更 UI を無効化。真偽値、または詳細制御（ドラッグ/表示）用の設定オブジェクト。プログラム API は引き続き利用可能。
customMobileEventRendererMobileEventRenderer任意—デフォルトのモバイル用イベントドロワー/ダイアログを置き換えるカスタムコンポーネント。
allDaySortComparatorAllDaySortComparator任意カレンダーグループ順（複数日終日は先頭）全ビューでの終日イベントの行順を制御するカスタム比較関数。指定するとデフォルト順を完全に上書きします。

それぞれのポイント

Views

  • 少なくとも 1 つのビューが必要です。defaultView が未指定の場合は週ビューが使われます。
  • ファクトリの戻り値は { type, component, config } から成る CalendarView。自作ビューを追加することも可能です。

Events

  • 渡した配列がそのままメモリ上のイベントストアになります。
  • CRUD は calendar.addEvent, calendar.updateEvent, calendar.deleteEvent を使うと即座に UI に反映されます。
  • Event インターフェースは Temporal の PlainDate / PlainDateTime / ZonedDateTime を受け付けます。

Plugins

  • プラグインは { name, install(app) } を持ち、初期化時に 1 度だけ実行されます。
  • ドラッグ&ドロップやキーボード操作、外部 API との橋渡しなどをここで拡張できます。
  • 複数のプラグインを同時に登録でき、それぞれ独立して動作します。
import { createDragPlugin } from '@dayflow/plugin-drag';
import { createEventsPlugin } from '@dayflow/core';

const dragPlugin = createDragPlugin({
  enableDrag: true,
  enableResize: true,
  enableCreate: true,
});

const eventsPlugin = createEventsPlugin({
  enableValidation: true,
  maxEventsPerDay: 100,
});

const calendar = useCalendarApp({
  views: [createWeekView(), createMonthView()],
  plugins: [dragPlugin, eventsPlugin],
});

Callbacks

コールバック役割
onViewChange(view)ビュー切り替え後に発火。アナリティクスや URL 同期に便利。
onDateChange(date)選択日が変わったときに発火。日付連動のサイドバーなどに。
onVisibleRangeChange(start, end, reason)可視日付範囲が変わるたびに発火。追加計算なしで、より正確なデータ取得に役立ちます。
onEventCreate / onEventUpdate / onEventDeleteイベント CRUD を捕捉。バックエンドと同期。
onEventDoubleClick(event, e)イベントがダブルクリックされたときに発火。e.currentTarget を外部ポップオーバーのアンカーに使え、false を返すと DayFlow の既定詳細パネル/ダイアログを抑止できます。
onMoreEventsClick(date)月ビューで「+ X 件」リンクがクリックされたときに発火。
onCalendarCreate / onCalendarUpdate / onCalendarDeleteカレンダーの追加・更新・削除を捕捉。
onCalendarMerge(sourceId, targetId)カレンダーのマージ操作を捕捉（例：「仕事」を「個人」に統合）。
onRender()レンダリング完了時に 1 度だけ発火。計測用。

defaultView と initialDate

  • 単一ビューのカレンダーでは必ず defaultView を明示的に設定してください。
  • initialDate はルーティング、ユーザー設定、またはサーバーデータから取得してマルチデバイス間の一貫性を保つことができます。

timeZone

  • timeZone は Day / Week / Month / Year 全体の主表示 / 編集タイムゾーンを定義します。
  • 未指定の場合、DayFlow はユーザーのシステムタイムゾーンを使います。
  • timeZone の変更は UI の再投影だけを行い、タイムゾーン変更そのものではイベントデータを書き換えません。
  • 編集系コールバックが返すのは canonical event のままです。UI 上で一時的に投影されたタイムゾーン値を、そのまま保存用データとして返すことはありません。
  • Day / Week の secondaryTimeZone は補助タイムライン専用で、アプリ全体の主タイムゾーンを置き換えるものではありません。

switcherMode

  • 'buttons': デスクトップ向けの水平ボタン群。
  • 'select': モバイルや画面幅が狭い場合に便利なセレクトボックス。

calendars & defaultCalendar

  • calendars に id, name, colors, darkColors, isVisible などを定義すると、イベントが calendarId を通じてスタイルを引き継ぎます。
  • defaultCalendar を設定しない場合は最初に可視状態のカレンダーが使われます。

CalendarType のプロパティ：

プロパティ型必須説明
idstringはい一意の識別子（例：'work'、'personal'）。
namestringはいUI に表示される名前。
colorsCalendarColorsはいライトモードのカラーセット（下表参照）。
darkColorsCalendarColorsいいえダークモードのカラーセット；省略時は colors にフォールバック。
descriptionstringいいえ任意の説明文。
iconstringいいえカレンダー名の横に表示する絵文字またはアイコン名。
isVisiblebooleanいいえこのカレンダーのイベントを表示するか。デフォルト true。
isDefaultbooleanいいえシステムデフォルトカレンダーとしてマークする。
readOnlybooleanいいえドラッグ・リサイズ・編集 UI を無効化する。
sourcestringいいえ取得元ラベル（例：'Google Calendar'、'iCloud'）。
subscription{ url, status, meta? }いいえICS / リモートカレンダーのサブスクリプションメタデータ。

CalendarColors のプロパティ：

プロパティ型説明
eventColorstringイベントの背景色（通常は半透明）。
eventSelectedColorstring選択時のイベント背景色。
lineColorstringアクセント / ボーダーカラー。
textColorstringイベントのテキストカラー。

theme

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

// 現在のテーマを取得
const currentTheme = calendar.app.getTheme();
calendar.app.setTheme('light');
calendar.app.subscribeThemeChange(theme => console.log(theme));

各カレンダータイプには colors と darkColors を用意しておくと、ライト/ダークの切替時も自然な配色になります。詳細は ダークモードガイド へ。

locale

locale オプションでカレンダーの言語と地域設定を行います。

  • 文字列: 'en-US', 'ja', 'zh', 'de', 'fr', 'es', 'ko' などの言語コードを指定します。
  • Locale オブジェクト: インポートした Locale オブジェクト（型安全性のため）またはカスタムオブジェクト（未サポート言語用）を渡します。
// 言語コード
const calendar = useCalendarApp({
  locale: 'ja',
});

// 組み込み Locale オブジェクト
import { ja } from '@dayflow/core';
const calendar = useCalendarApp({
  locale: ja,
});

// カスタム Locale オブジェクト
const customLocale = {
  code: 'it',
  messages: { today: 'Oggi', ... }
};
const calendar = useCalendarApp({
  locale: customLocale,
});

useEventDetailDialog

  • true：デフォルトのモーダルダイアログ（DefaultEventDetailDialog）を有効にします。
  • DayFlowCalendar の customDetailPanelContent または customEventDetailDialog と組み合わせると、内部のステートマシンを保ちながら UI を差し替えられます。

useCalendarHeader

  • true（デフォルト）：組み込みカレンダーヘッダーを表示します。
  • false：ヘッダーを完全に非表示にします。

カスタムヘッダーをレンダリングするには、DayFlowCalendar の calendarHeader スロットを使用してください。詳細は Calendar Header を参照してください。

readOnly

  • true：組み込みの変更 UI（ドラッグ、作成、編集）を無効にします。
  • ReadOnlyConfig：詳細制御：
    • draggable：ドラッグ操作を許可するかどうか。
    • viewable：イベント詳細の表示を許可するかどうか。
  • calendar.addEvent()、calendar.updateEvent()、calendar.deleteEvent()、calendar.applyEventsChanges() などのプログラム API は、読み取り専用モードでも利用できます。
  • カスタム UI では calendar.canMutateFromUI() を使って、作成・編集・削除操作を表示してよいか判定してください。
  • 詳細は 読み取り専用モード を参照してください。

customMobileEventRenderer

  • モバイル用のデフォルトのイベント編集ドロワーを独自のコンポーネントで置き換えることができます。
  • 詳細はサイドバープラグインを参照してください。

allDaySortComparator

全ビュー（日・週・月・年）での終日イベントの行順を制御します。

デフォルトでは DayFlow が次のルールで並べます：

  • calendarId の初出現順でグループ化する
  • 複数日にまたがる終日イベントを単日終日イベントより上に配置する
  • 同じカレンダーの終日イベントはできるだけ隣接した順序を保つ

allDaySortComparator は、最終的な順序を完全に自分で決めたい場合にだけ渡してください。指定した場合は、その比較結果がそのまま最終順序として使われます。

比較関数を渡すと完全に制御できます — 2 つの Event オブジェクトを受け取り、JavaScript の Array.sort と同じ動作です：

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

そのまま使えるエクスポート済みヘルパー（@dayflow/core からエクスポート）：

ヘルパー動作
sortAllDayByTitleタイトルのアルファベット順で終日イベントを並べる。デフォルトのグループ順は適用されません
import { sortAllDayByTitle } from '@dayflow/core';

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

updateConfig を使うとランタイムで変更できます：

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

// デフォルトのカレンダーグループ順に戻す
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: '仕事',
    colors: {
      eventColor: '#2563eb',
      eventSelectedColor: '#1d4ed8',
      lineColor: '#1e40af',
      textColor: '#ffffff',
    },
  },
  {
    id: 'personal',
    name: 'プライベート',
    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 が返すインスタンスをカレンダー本体・ヘッダー・サイドバーなど複数のコンポーネントで共有すると、状態が常に同期されたまま UI を構築できます。

関連ドキュメント

DayFlowCalendar

Previous Page

プラグインの概要

Next Page

On this page

useCalendarApp
クイックスタート
主な設定項目
それぞれのポイント
Views
Events
Plugins
Callbacks
defaultView と initialDate
timeZone
switcherMode
calendars & defaultCalendar
theme
locale
useEventDetailDialog
useCalendarHeader
readOnly
customMobileEventRenderer
allDaySortComparator
応用的な設定例
関連ドキュメント