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

> 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.

# Calendar 日历

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


## 基础用法

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


2026年**10**月

月年

今天

周一一周二二周三三周四四周五五周六六周日日

28

29

30

10月1日

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

11月1日

2

3

4

5

6

7

8

basic.tsx

复制代码

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

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

展开代码


## 示例

### 紧凑日历

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


2026年**10**月

一一二二三三四四五五六六日日

28

29

30

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

1

2

3

4

5

6

7

8

compact.tsx

复制代码

```tsx lineNumbers file="../../src/examples/calendar/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**年

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)} />;
}
```

展开代码

### 受控日期与展示月份

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


2026年**10**月

查看所选月份

月年

今天

周一一周二二周三三周四四周五五周六六周日日

28

29

30

10月1日

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

11月1日

2

3

4

5

6

7

8

已选日期：2026-10-15

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/calendar/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**月

月年

今天

周一一周二二周三三周四四周五五周六六周日日

28

29

30

10月1日

2

3

4

5

6

7

8项目评审

9

10

11

12

13

14

15版本发布

16

17

18

19

20

21

22设计同步

23

24

25

26

27

28

29

30

31

11月1日

2

3

4

5

6

7

8

schedule.tsx

复制代码

```tsx lineNumbers file="../../src/examples/calendar/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 页面应提供服务端和客户端一致的初始日期，见 [服务端渲染](https://ifhover.github.io/leaf-ui/guide/ssr.md)。Calendar 不提供原生表单提交或重置行为，需要这些能力时使用 [DatePicker](https://ifhover.github.io/leaf-ui/components/date-picker.md)。


## API

### Calendar API

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

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