DayFlowCalendar

DayFlowCalendar 是日历组件的核心容器，负责渲染当前选中的视图、处理整体布局，并集成可选 UI 元素（如侧边栏和事件详情弹窗）。配合 useCalendarApp 和视图工厂函数，您可以用最少的代码快速构建功能完整的日历应用。

基础用法

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

export function CalendarDemo() {
  const calendar = useCalendarApp({
    views: [createWeekView()],
    defaultView: ViewType.WEEK,
    initialDate: new Date(),
    events: [],
    plugins: [createSidebarPlugin()],
  });

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

该组件接收来自 useCalendarApp 的 calendar 对象，读取当前激活的视图，并渲染对应的视图组件。可以在 DayFlowCalendar 外部放置工具栏或其他自定义 UI，该组件本身已内置：

可选日历侧边栏（通过 createSidebarPlugin 插件添加）
事件详情弹窗支持（可通过 useEventDetailDialog 或自定义渲染器驱动）
日历切换或视图变更时的自动布局更新

属性说明

属性名	类型	说明	必填
`calendar`	`UseCalendarAppReturn`	`useCalendarApp` 的返回结果，提供状态管理、视图注册、侧边栏配置等能力	必填
`collapsedSafeAreaLeft`	`number`	侧边栏折叠时的左内边距（px），用于兼容 Mac 红绿灯按钮区域	可选
`search`	`CalendarSearchProps`	内置搜索功能的配置项	可选

搜索配置

search 属性允许您自定义内置搜索的行为。默认情况下，它会在本地搜索事件的标题和描述。

<DayFlowCalendar
  calendar={calendar}
  search={{
    debounceDelay: 500,
    emptyText: '未找到相关事件',
    onSearch: async keyword => {
      // 自定义异步搜索（例如从 API 获取）
      return fetch(`/api/search?q=${keyword}`).then(res => res.json());
    },
  }}
/>

Search Props

选项	描述
`debounceDelay`	触发搜索前的防抖延迟时间（毫秒）。
`onSearch`	基于关键词获取结果的异步函数。
`customSearch`	使用自定义逻辑在本地过滤事件的同步函数。
`onResultClick`	点击搜索结果时的回调。包含一个 `defaultAction` 回调用于触发内置的跳转逻辑（跳转到事件日期、高亮该事件并在移动端自动关闭搜索界面）。如果不调用 `defaultAction()`，则需要自行处理所有的跳转和 UI 状态切换。
`emptyText`	未找到结果时显示的文本。

侧边栏配置

侧边栏通过安装并添加 @dayflow/plugin-sidebar 插件来启用：

import { createSidebarPlugin } from '@dayflow/plugin-sidebar';

const calendar = useCalendarApp({
  views: [createWeekView()],
  plugins: [
    createSidebarPlugin({
      width: 280,
      initialCollapsed: false,
      createCalendarMode: 'modal', // 'inline' 或 'modal'
    }),
  ],
});

return <DayFlowCalendar calendar={calendar} />;

当添加 createSidebarPlugin() 插件后，会渲染默认侧边栏，包含日历筛选器和全选控制功能
可以自定义宽度、默认折叠状态，或通过 render 或 renderSidebarHeader 提供自定义渲染器。renderSidebarHeader 允许您在保留侧边栏整体布局的同时，仅替换头部区域（标题和折叠按钮）

事件详情展示

DayFlow 提供三种事件详情展示方式：

默认面板模式 — useEventDetailDialog 为 false（默认值）时，点击事件会打开内置的浮动面板 DefaultEventDetailPanel。使用 eventDetailContent 插槽可在保留默认面板框架的同时替换面板内容。
弹窗模式 — 在 useCalendarApp 中设置 useEventDetailDialog: true 可启用内置居中模态框。使用 eventDetailDialog 插槽可替换为您自定义的弹窗 UI。
完全关闭 — 若您的应用通过回调或全局状态管理事件详情，可在 useCalendarApp 中设置 useEventDetailPanel: false 来完全隐藏浮动面板。

// 隐藏内置面板 — 在其他地方使用自定义模态框
const calendar = useCalendarApp({
  ...
  useEventDetailPanel: false,
});

return <DayFlowCalendar calendar={calendar} />;

// 自定义面板内容（保留默认面板框架）
<DayFlowCalendar
  calendar={calendar}
  eventDetailContent={({ event, onClose }) => (
    <div className='p-4'>
      <h2>{event.title}</h2>
      <button onClick={onClose}>关闭</button>
    </div>
  )}
/>

// 自定义弹窗（需要在 useCalendarApp 中设置 useEventDetailDialog: true）
<DayFlowCalendar
  calendar={calendar}
  eventDetailDialog={({ event, isOpen, onClose }) => (
    <MyDialog isOpen={isOpen} onClose={onClose}>
      <EventForm event={event} />
    </MyDialog>
  )}
/>

总而言之，DayFlowCalendar 承担了协调层的职责——处理整体布局、侧边栏集成和事件详情逻辑，专注于配置 useCalendarApp 和构建周边的产品体验。