For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/calendar.md.

Calendar 日历

浏览和选择日期,也可在日期中补充日程信息。

基础用法

通过 defaultValue 设置初始选中日期;选择日期时触发 onChange。

2026年10月
basic.tsx
import { Calendar } from '@ifhover/leaf-ui';

export function CalendarBasic() {
  return <Calendar defaultValue={new Date(2026, 9, 4)} />;
}

示例

紧凑日历

设置 fullscreen={false} 使用紧凑日历。下面通过 disabledDate 排除周末;点击标题可切换到月份视图。

compact.tsx
import { Calendar } from '@ifhover/leaf-ui';

export function CalendarCompact() {
  return (
    <Calendar
      fullscreen={false}
      defaultValue={new Date(2026, 9, 6)}
      disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
    />
  );
}

选择月份

mode="month" 直接选择月份,返回所选月份第一天的本地 Date。此模式的 disabledDate 也接收月初日期。

2026年
month.tsx
import { Calendar } from '@ifhover/leaf-ui';

export function CalendarMonth() {
  return <Calendar fullscreen={false} mode="month" defaultValue={new Date(2026, 9, 1)} />;
}

受控日期与展示月份

value 管理选中日期,visibleDate 管理正在查看的月份。翻页或点击“今天”只改变展示月份,不会选择日期;onVisibleChange 返回新月份的第一天。示例通过 headerExtra 提供返回所选月份的操作。

2026年10月
已选日期:2026-10-15
controlled.tsx
import { Button, Calendar, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

function formatDate(date: Date) {
  return [date.getFullYear(), date.getMonth() + 1, date.getDate()]
    .map((part, index) => (index === 0 ? String(part) : String(part).padStart(2, '0')))
    .join('-');
}

export function CalendarControlled() {
  const [value, setValue] = useState(new Date(2026, 9, 15));
  const [visibleDate, setVisibleDate] = useState(new Date(2026, 9, 1));

  return (
    <Flex direction="column" gap="md">
      <Calendar
        value={value}
        onChange={setValue}
        visibleDate={visibleDate}
        onVisibleChange={setVisibleDate}
        headerExtra={
          <Button size="sm" onClick={() => setVisibleDate(value)}>
            查看所选月份
          </Button>
        }
      />
      <Text tone="muted" role="status">
        已选日期:{formatDate(value)}
      </Text>
    </Flex>
  );
}

日程内容

通过 cellRender 补充文字、图标或 Tag。内容放在日期按钮内,不能嵌套链接、按钮等交互元素;需要操作日程时,在日历外提供对应入口。

2026年10月
schedule.tsx
import { Calendar, Tag } from '@ifhover/leaf-ui';

const events: Record<string, string> = {
  '2026-10-8': '项目评审',
  '2026-10-15': '版本发布',
  '2026-10-22': '设计同步',
};

export function CalendarSchedule() {
  return (
    <Calendar
      defaultValue={new Date(2026, 9, 4)}
      cellRender={(date) => {
        const event = events[`${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`];
        return event ? <Tag>{event}</Tag> : null;
      }}
    />
  );
}

日期使用本地 Date;minDate / maxDate 包含边界日期。SSR 页面应提供服务端和客户端一致的初始日期,见 服务端渲染。Calendar 不提供原生表单提交或重置行为,需要这些能力时使用 DatePicker。

API

Calendar API

选中日期、显示月份与可选日期范围的配置。

属性类型默认值说明
valueDate—受控的选中日期,与 visibleDate 独立。
defaultValueDate—非受控模式的初始选中日期。
onChange(date: Date) => void—选择日期时调用;month 模式返回所选月的第一天。
mode'date' | 'month''date'选择日期或月份
fullscreenbooleantrue完整月历布局;false 为 296px 紧凑日历
minDateDate—日期边界
maxDateDate—日期边界
disabledDate(date: Date) => boolean—禁用指定日期
visibleDateDate—受控的显示月份,不代表选中日期。
onVisibleChange(date: Date) => void—显示月份变化时返回新月份的第一天;不触发选择。
showTodaybooleantrue显示回到今天的操作,仅切换显示月份,不改变选中值。
cellRender(date: Date) => ReactNode—自定义单元格内容;内容位于选择按钮内,不要嵌套交互控件。
headerExtraReactNode—标题区域补充内容