> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/calendar.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# Calendar 日历

查看日期、选择日期并展示日程安排。

## 日程日历


10月2026

今天

一二三四五六日

28293012345678项目评审9101112131415发布16171819202122设计同步23242526272829303112345678

已选日期: 2026-10-4

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/calendar/basic.tsx"
import { Calendar, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

const events: Record<number, { label: string; color: string }> = {
  8: { label: '项目评审', color: '#20834a' },
  15: { label: '发布', color: '#1677ff' },
  22: { label: '设计同步', color: '#7654c6' },
};

export function CalendarBasic() {
  const [value, setValue] = useState(new Date(2026, 9, 4));
  return (
    <Space direction="vertical" align="stretch">
      <Calendar
        value={value}
        onChange={setValue}
        cellRender={(date) => {
          const event = date.getMonth() === 9 ? events[date.getDate()] : undefined;
          return event ? <Text style={{ color: event.color }}>{event.label}</Text> : null;
        }}
      />
      <output>
        <Text tone="muted">
          已选日期: {value.getFullYear()}-{value.getMonth() + 1}-{value.getDate()}
        </Text>
      </output>
    </Space>
  );
}
```

展开代码

## 紧凑日历与禁用日期


10月2026

一二三四五六日

2829301234567891011121314151617181920212223242526272829303112345678

周末不可选；已有的选中日期仍清晰可见。

compact.tsx

复制代码

```tsx lineNumbers file="../../src/examples/calendar/compact.tsx"
import { Calendar, Space, Text } from '@ifhover/leaf-ui';

export function CalendarCompact() {
  return (
    <Space direction="vertical" align="stretch">
      <Calendar
        fullscreen={false}
        defaultValue={new Date(2026, 9, 4)}
        disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
      />
      <Text tone="muted">周末不可选；已有的选中日期仍清晰可见。</Text>
    </Space>
  );
}
```

展开代码

## 选择月份


2026

1月2月3月4月5月6月7月8月9月10月11月12月

month.tsx

复制代码

```tsx lineNumbers file="../../src/examples/calendar/month.tsx"
import { Calendar } from '@ifhover/leaf-ui';

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

展开代码

## Calendar API

| 属性                     | 类型                          | 默认值      | 说明                |
| ---------------------- | --------------------------- | -------- | ----------------- |
| `value / defaultValue` | `Date`                      | —        | 受控 / 初始选中日期       |
| `onChange`             | `(date: Date) => void`      | —        | 选择日期后触发           |
| `visibleDate`          | `Date`                      | —        | 受控展示范围            |
| `onVisibleChange`      | `(date: Date) => void`      | —        | 展示范围变化            |
| `mode`                 | `'date' \| 'month'`         | `'date'` | 选择日期或月份           |
| `fullscreen`           | `boolean`                   | `true`   | 完整日历布局            |
| `minDate / maxDate`    | `Date`                      | —        | 日期边界              |
| `disabledDate`         | `(date: Date) => boolean`   | —        | 禁用指定日期            |
| `cellRender`           | `(date: Date) => ReactNode` | —        | 补充日程内容            |
| `headerExtra`          | `ReactNode`                 | —        | 标题区域补充内容          |
| `showToday`            | `boolean`                   | `true`   | 完整日历展示今天按钮，跳至当前月份 |

## 类型

可导入以下类型定义属性、组装数据或处理回调。

```ts
import type { CalendarProps } from '@ifhover/leaf-ui';
```

## 使用说明

`fullscreen={false}` 展示紧凑日历。`cellRender` 中使用文字、图标等非交互内容，避免在日期按钮内嵌套按钮。禁用选中项保留清晰的灰色状态，不会再次触发选择。

方向键移动日期，Home / End 跳至一行首尾，PageUp / PageDown 切换月份。SSR 页面应提供一致的初始日期，详见 [服务端渲染](https://ifhover.github.io/leaf-ui/v/0.6.0/guide/ssr.md)。