日历 Calendar - Mogu Design

按照日历形式展示数据的容器。

何时使用

当数据是日期或按照日期划分时，例如日程、课表、价格日历等，农历等。目前支持年/月切换。

代码演示

2025年

3月

月年

一	二	三	四	五	六	日
24	25	26	27	28	01	02
03	04	05	06	07	08	09
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	01	02	03	04	05	06

一个通用的日历面板，支持年/月切换。

TypeScript
JavaScript
import React from 'react';
import { Calendar } from 'mogud';
import type { Dayjs } from 'dayjs';
import type { CalendarMode } from 'mogud/es/calendar/generateCalendar';

const App: React.FC = () => {
  const onPanelChange = (value: Dayjs, mode: CalendarMode) => {
    console.log(value.format('YYYY-MM-DD'), mode);
  };

  return <Calendar onPanelChange={onPanelChange} />;
};

export default App;

2025年

3月

月年

一	二	三	四	五	六	日
24	25	26	27	28	01	02
03	04	05	06	07	08 This is warning event. This is usual event.	09
10 This is warning event. This is usual event. This is error event.	11	12	13	14	15 This is warning event This is very long usual event.... This is error event 1. This is error event 2. This is error event 3. This is error event 4.	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	01	02	03	04	05	06

通知事项日历

一个复杂的应用示例，用 dateCellRender 和 monthCellRender 函数来自定义需要渲染的数据。

TypeScript
JavaScript
import React from 'react';
import type { BadgeProps } from 'mogud';
import { Badge, Calendar } from 'mogud';
import type { Dayjs } from 'dayjs';
import type { CellRenderInfo } from 'rc-picker/lib/interface';

const getListData = (value: Dayjs) => {
  let listData;
  switch (value.date()) {
    case 8:
      listData = [
        { type: 'warning', content: 'This is warning event.' },
        { type: 'success', content: 'This is usual event.' },
      ];
      break;
    case 10:
      listData = [
        { type: 'warning', content: 'This is warning event.' },
        { type: 'success', content: 'This is usual event.' },
        { type: 'error', content: 'This is error event.' },
      ];
      break;
    case 15:
      listData = [
        { type: 'warning', content: 'This is warning event' },
        { type: 'success', content: 'This is very long usual event....' },
        { type: 'error', content: 'This is error event 1.' },
        { type: 'error', content: 'This is error event 2.' },
        { type: 'error', content: 'This is error event 3.' },
        { type: 'error', content: 'This is error event 4.' },
      ];
      break;
    default:
  }
  return listData || [];
};

const getMonthData = (value: Dayjs) => {
  if (value.month() === 8) {
    return 1394;
  }
};

const App: React.FC = () => {
  const monthCellRender = (value: Dayjs) => {
    const num = getMonthData(value);
    return num ? (
      <div className="notes-month">
        <section>{num}</section>
        <span>Backlog number</span>
      </div>
    ) : null;
  };

  const dateCellRender = (value: Dayjs) => {
    const listData = getListData(value);
    return (
      <ul className="events">
        {listData.map((item) => (
          <li key={item.content}>
            <Badge status={item.type as BadgeProps['status']} text={item.content} />
          </li>
        ))}
      </ul>
    );
  };

  const cellRender = (current: Dayjs, info: CellRenderInfo<Dayjs>) => {
    if(info.type === 'date') return dateCellRender(current);
    if(info.type === 'month') return monthCellRender(current);
    return info.originNode;
  };

  return <Calendar cellRender={cellRender} />;
};

export default App;
.events {
  margin: 0;
  padding: 0;
  list-style: none;
}
.events .ant-badge-status {
  width: 100%;
  overflow: hidden;
  font-size: 12px;
  white-space: nowrap;
  text-overflow: ellipsis;
}
.notes-month {
  font-size: 28px;
  text-align: center;
}
.notes-month section {
  font-size: 28px;
}

2025年

3月

月年

一	二	三	四	五	六	日
24	25	26	27	28	01	02
03	04	05	06	07	08	09
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	01	02	03	04	05	06

用于嵌套在空间有限的容器中。

TypeScript
JavaScript
import { Calendar, theme } from 'mogud';
import type { CalendarMode } from 'mogud/es/calendar/generateCalendar';
import type { Dayjs } from 'dayjs';
import React from 'react';

const onPanelChange = (value: Dayjs, mode: CalendarMode) => {
  console.log(value.format('YYYY-MM-DD'), mode);
};

const App: React.FC = () => {
  const { token } = theme.useToken();

  const wrapperStyle: React.CSSProperties = {
    width: 300,
    border: `1px solid ${token.colorBorderSecondary}`,
    borderRadius: token.borderRadiusLG,
  };

  return (
    <div style={wrapperStyle}>
      <Calendar fullscreen={false} onPanelChange={onPanelChange} />
    </div>
  );
};

export default App;

You selected date: 2017-01-25

2017年

1月

月年

一	二	三	四	五	六	日
26	27	28	29	30	31	01
02	03	04	05	06	07	08
09	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30	31	01	02	03	04	05

一个通用的日历面板，支持年/月切换。

TypeScript
JavaScript
import React, { useState } from 'react';
import { Alert, Calendar } from 'mogud';
import type { Dayjs } from 'dayjs';
import dayjs from 'dayjs';

const App: React.FC = () => {
  const [value, setValue] = useState(() => dayjs('2017-01-25'));
  const [selectedValue, setSelectedValue] = useState(() => dayjs('2017-01-25'));

  const onSelect = (newValue: Dayjs) => {
    setValue(newValue);
    setSelectedValue(newValue);
  };

  const onPanelChange = (newValue: Dayjs) => {
    setValue(newValue);
  };

  return (
    <>
      <Alert message={`You selected date: ${selectedValue?.format('YYYY-MM-DD')}`} />
      <Calendar value={value} onSelect={onSelect} onPanelChange={onPanelChange} />
    </>
  );
};

export default App;

Custom header

MonthYear

2025

Mar

一	二	三	四	五	六	日
24	25	26	27	28	01	02
03	04	05	06	07	08	09
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31	01	02	03	04	05	06

自定义头部

自定义日历头部内容。

TypeScript
JavaScript
import React from 'react';
import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn';
import type { Dayjs } from 'dayjs';
import dayLocaleData from 'dayjs/plugin/localeData';
import { Calendar, Col, Radio, Row, Select, Typography, theme } from 'mogud';
import type { CalendarMode } from 'mogud/es/calendar/generateCalendar';

dayjs.extend(dayLocaleData);

const App: React.FC = () => {
  const { token } = theme.useToken();

  const onPanelChange = (value: Dayjs, mode: CalendarMode) => {
    console.log(value.format('YYYY-MM-DD'), mode);
  };

  const wrapperStyle = {
    width: 300,
    border: `1px solid ${token.colorBorderSecondary}`,
    borderRadius: token.borderRadiusLG,
  };

  return (
    <div style={wrapperStyle}>
      <Calendar
        fullscreen={false}
        headerRender={({ value, type, onChange, onTypeChange }) => {
          const start = 0;
          const end = 12;
          const monthOptions = [];

          let current = value.clone();
          const localeData = value.localeData();
          const months = [];
          for (let i = 0; i < 12; i++) {
            current = current.month(i);
            months.push(localeData.monthsShort(current));
          }

          for (let i = start; i < end; i++) {
            monthOptions.push(
              <Select.Option key={i} value={i} className="month-item">
                {months[i]}
              </Select.Option>,
            );
          }

          const year = value.year();
          const month = value.month();
          const options = [];
          for (let i = year - 10; i < year + 10; i += 1) {
            options.push(
              <Select.Option key={i} value={i} className="year-item">
                {i}
              </Select.Option>,
            );
          }
          return (
            <div style={{ padding: 8 }}>
              <Typography.Title level={4}>Custom header</Typography.Title>
              <Row gutter={8}>
                <Col>
                  <Radio.Group
                    size="small"
                    onChange={(e) => onTypeChange(e.target.value)}
                    value={type}
                  >
                    <Radio.Button value="month">Month</Radio.Button>
                    <Radio.Button value="year">Year</Radio.Button>
                  </Radio.Group>
                </Col>
                <Col>
                  <Select
                    size="small"
                    dropdownMatchSelectWidth={false}
                    className="my-year-select"
                    value={year}
                    onChange={(newYear) => {
                      const now = value.clone().year(newYear);
                      onChange(now);
                    }}
                  >
                    {options}
                  </Select>
                </Col>
                <Col>
                  <Select
                    size="small"
                    dropdownMatchSelectWidth={false}
                    value={month}
                    onChange={(newMonth) => {
                      const now = value.clone().month(newMonth);
                      onChange(now);
                    }}
                  >
                    {monthOptions}
                  </Select>
                </Col>
              </Row>
            </div>
          );
        }}
        onPanelChange={onPanelChange}
      />
    </div>
  );
};

export default App;

API

注意：Calendar 部分 locale 是从 value 中读取，所以请先正确设置 dayjs 的 locale。

// 默认语言为 en-US，所以如果需要使用其他语言，推荐在入口文件全局设置 locale
// import dayjs from 'dayjs';
// import 'dayjs/locale/zh-cn';
// dayjs.locale('zh-cn');

<Calendar
  dateCellRender={dateCellRender}
  monthCellRender={monthCellRender}
  onPanelChange={onPanelChange}
  onSelect={onSelect}
/>

参数	说明	类型	默认值	版本
dateCellRender	自定义渲染日期单元格，返回内容会被追加到单元格，>= 5.4.0 请用 `cellRender`	function(date: Dayjs): ReactNode	-	< 5.4.0
cellRender	自定义单元格的内容	function(current: dayjs, today: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' \| 'end', type: PanelMode, locale?: Locale, subType?: 'hour' \| 'minute' \| 'second' \| 'meridiem' }) => React.ReactNode	-	5.4.0
dateFullCellRender	自定义渲染日期单元格，返回内容覆盖单元格，>= 5.4.0 请用 `fullCellRender`	function(date: Dayjs): ReactNode	-	< 5.4.0
fullCellRender	自定义单元格的内容	function(current: dayjs, today: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' \| 'end', type: PanelMode, locale?: Locale, subType?: 'hour' \| 'minute' \| 'second' \| 'meridiem' }) => React.ReactNode	-	5.4.0
defaultValue	默认展示的日期	dayjs	-
disabledDate	不可选择的日期，参数为当前 `value`，注意使用时不要直接修改	(currentDate: Dayjs) => boolean	-
fullscreen	是否全屏显示	boolean	true
headerRender	自定义头部内容	function(object:{value: Dayjs, type: string, onChange: f(), onTypeChange: f()})	-
locale	国际化配置	object	(默认配置)
mode	初始模式	`month` \| `year`	`month`
monthCellRender	自定义渲染月单元格，返回内容会被追加到单元格，>= 5.4.0 请用 `cellRender`	function(date: Dayjs): ReactNode	-	< 5.4.0
cellRender	自定义单元格的内容	function(current: dayjs, today: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' \| 'end', type: PanelMode, locale?: Locale, subType?: 'hour' \| 'minute' \| 'second' \| 'meridiem' }) => React.ReactNode	-	5.4.0
monthFullCellRender	自定义渲染月单元格，返回内容覆盖单元格，>= 5.4.0 请用 `fullCellRender`	function(date: Dayjs): ReactNode	-	< 5.4.0
fullCellRender	自定义单元格的内容	function(current: dayjs, today: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' \| 'end', type: PanelMode, locale?: Locale, subType?: 'hour' \| 'minute' \| 'second' \| 'meridiem' }) => React.ReactNode	-	5.4.0
validRange	设置可以显示的日期	[dayjs, dayjs]	-
value	展示日期	dayjs	-
onChange	日期变化回调	function(date: Dayjs)	-
onPanelChange	日期面板变化回调	function(date: Dayjs, mode: string)	-
onSelect	选择日期回调，包含来源信息	function(date: Dayjs, info: { source: 'year' \| 'month' \| 'date' \| 'customize' })	-	`info`: 5.6.0

FAQ

如何在 Calendar 中使用自定义日期库

参考使用自定义日期库。

如何给日期类组件配置国际化？

参考如何给日期类组件配置国际化。

为什么时间类组件的国际化 locale 设置不生效？

参考 FAQ 为什么时间类组件的国际化 locale 设置不生效？。

如何仅获取来自面板点击的日期？

onSelect 事件提供额外的来源信息，你可以通过 info.source 来判断来源：

<Calendar
  onSelect={(date, { source }) => {
    if (source === 'date') {
      console.log('Panel Select:', source);
    }
  }}
/>