Skip to content

docs(calendar): update range api desc #791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
uyarn merged 3 commits into from
Dec 31, 2025
Merged

docs(calendar): update range api desc #791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6229750
docs(calendar): update `range` api desc
shumuuu Dec 17, 2025
5771cb9
docs(calendar): add `CalendarValue` ts definition
shumuuu Dec 17, 2025
49a1fc8
chore: resolve conflict
github-actions[bot] Dec 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified db/TDesign.db
View file
Open in desktop
Binary file not shown.
56 changes: 32 additions & 24 deletions packages/products/tdesign-react/packages/components/calendar/calendar.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,50 +5,58 @@

name | type | default | description | required
-- | -- | -- | -- | --
className | String | - | 类名 | N
style | Object | - | 样式，Typescript：`React.CSSProperties` | N
cell | TNode | - | Typescript：`string \| TNode<CalendarCell>`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts) | N
cellAppend | TNode | - | Typescript：`string \| TNode<CalendarCell>`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts) | N
controllerConfig | Boolean / Object | undefined | Typescript：`boolean \| CalendarController` | N
className | String | - | className of component | N
style | Object | - | CSS(Cascading Style Sheets)，Typescript: `React.CSSProperties` | N
cell | TNode | - | Typescript: `string \| TNode<CalendarCell>`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts) | N
cellAppend | TNode | - | Typescript: `string \| TNode<CalendarCell>`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts) | N
controllerConfig | Boolean / Object | undefined | Typescript: `boolean \| CalendarController` | N
fillWithZero | Boolean | true | \- | N
firstDayOfWeek | Number | 1 | options：1/2/3/4/5/6/7 | N
firstDayOfWeek | Number | 1 | options: 1/2/3/4/5/6/7 | N
format | String | 'YYYY-MM-DD' | \- | N
head | TNode | - | Typescript：`string \| TNode<ControllerOptions>`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts) | N
head | TNode | - | Typescript: `string \| TNode<ControllerOptions>`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts) | N
isShowWeekendDefault | Boolean | true | \- | N
mode | String | month | options：month/year | N
mode | String | month | options: month/year | N
month | String / Number | - | \- | N
multiple | Boolean | - | \- | N
preventCellContextmenu | Boolean | false | \- | N
range | Array | - | Typescript：`Array<CalendarValue>` | N
theme | String | full | options：full/card | N
value | String / Array / Date | - | Typescript：`CalendarValue \| CalendarValue[]` `type CalendarValue = string \| Date`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
week | TNode | - | Typescript：`Array<string> \| TNode<CalendarWeek>` `interface CalendarWeek { day: WeekDay }` `type WeekDay = 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
range | Array | - | Set the year and month display range of calendar, [start, end]. Example 1: `['2018-08', '2028-04']`. Example 2: `[new Date(2018, 8), new Date(2028, 4)]`. Only when both items from the input list can be parsed normally by `dayjs` can the specified calendar range take effect, while you can set the start or end of the range separately by inputting a list with only one item that can be parsed normally。Typescript: `Array<CalendarValue>` `type CalendarValue = string \| Date`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
theme | String | full | options: full/card | N
value | String / Array / Date | - | Typescript: `CalendarValue \| CalendarValue[]` `type CalendarValue = string \| Date`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
week | TNode | - | Typescript: `Array<string> \| TNode<CalendarWeek>` `interface CalendarWeek { day: WeekDay }` `type WeekDay = 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
year | String / Number | - | \- | N
onCellClick | Function | | Typescript：`(options: { cell: CalendarCell; e: MouseEvent }) => void`<br/> | N
onCellDoubleClick | Function | | Typescript：`(options: { cell: CalendarCell; e: MouseEvent }) => void`<br/> | N
onCellRightClick | Function | | Typescript：`(options: { cell: CalendarCell; e: MouseEvent }) => void`<br/> | N
onControllerChange | Function | | Typescript：`(options: ControllerOptions) => void`<br/>[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts)。<br/>`interface ControllerOptions { filterDate: Date; formattedFilterDate: string; mode: string; isShowWeekend: boolean }`<br/> | N
onMonthChange | Function | | Typescript：`(options: { month: string; year: string }) => void`<br/> | N
onCellClick | Function | | Typescript: `(options: { cell: CalendarCell; e: MouseEvent }) => void`<br/> | N
onCellDoubleClick | Function | | Typescript: `(options: { cell: CalendarCell; e: MouseEvent }) => void`<br/> | N
onCellRightClick | Function | | Typescript: `(options: { cell: CalendarCell; e: MouseEvent }) => void`<br/> | N
onControllerChange | Function | | Typescript: `(options: ControllerOptions) => void`<br/>[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts)。<br/>`interface ControllerOptions { filterDate: Date; formattedFilterDate: string; mode: string; isShowWeekend: boolean }`<br/> | N
onMonthChange | Function | | Typescript: `(options: { month: string; year: string }) => void`<br/> | N

### CalendarInstanceFunctions 组件实例方法

name | params | return | description
-- | -- | -- | --
className | String | - | className of component | N
style | Object | - | CSS(Cascading Style Sheets)，Typescript: `React.CSSProperties` | N
toCurrent | \- | \- | go to today

### CalendarController

name | type | default | description | required
-- | -- | -- | -- | --
current | Object | - | Typescript：`{ visible?: boolean; currentDayButtonProps?: ButtonProps; currentMonthButtonProps?: ButtonProps }`，[Button API Documents](./button?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
current | Object | - | Typescript: `{ visible?: boolean; currentDayButtonProps?: ButtonProps; currentMonthButtonProps?: ButtonProps }`，[Button API Documents](./button?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
disabled | Boolean | false | \- | N
mode | Object | - | Typescript：`{ visible?: boolean; radioGroupProps?: RadioGroupProps }`，[Radio API Documents](./radio?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
month | Object | - | Typescript：`{ visible?: boolean; selectProps?: SelectProps }` | N
weekend | Object | - | Typescript：`{ visible?: boolean; showWeekendButtonProps?: CheckTagProps; hideWeekendButtonProps?: CheckTagProps }`，[Tag API Documents](./tag?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
year | Object | - | Typescript：`{ visible?: boolean; selectProps?: SelectProps }`，[Select API Documents](./select?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
mode | Object | - | Typescript: `{ visible?: boolean; radioGroupProps?: RadioGroupProps }`，[Radio API Documents](./radio?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
month | Object | - | Typescript: `{ visible?: boolean; selectProps?: SelectProps }` | N
weekend | Object | - | Typescript: `{ visible?: boolean; showWeekendButtonProps?: CheckTagProps; hideWeekendButtonProps?: CheckTagProps }`，[Tag API Documents](./tag?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
year | Object | - | Typescript: `{ visible?: boolean; selectProps?: SelectProps }`，[Select API Documents](./select?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N

### CalendarCell

name | type | default | description | required
-- | -- | -- | -- | --
belongTo | Number | - | \- | N
date | Object | - | Typescript：`Date` | N
date | Object | - | Typescript: `Date` | N
day | Number | - | \- | N
formattedDate | String | - | \- | N
isCurrent | Boolean | - | \- | N
weekOrder | Number | - | \- | N
`ControllerOptions` | \- | - | \- | N
`ControllerOptions` | \- | - | extends `ControllerOptions` | N
18 changes: 13 additions & 5 deletions packages/products/tdesign-react/packages/components/calendar/calendar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## API
### Calendar Props

名称 | 类型 | 默认值 | 说明 | 必传
名称 | 类型 | 默认值 | 描述 | 必传
-- | -- | -- | -- | --
className | String | - | 类名 | N
style | Object | - | 样式，TS 类型：`React.CSSProperties` | N
Expand All @@ -19,7 +19,7 @@ mode | String | month | 日历展示维度。可选项：month/year | N
month | String / Number | - | 控制当前面板展示月份，优先级高于 `controllerConfig.month` | N
multiple | Boolean | - | 是否高亮多个日期单元格 | N
preventCellContextmenu | Boolean | false | 是否禁用单元格右键默认系统菜单 | N
range | Array | - | 用于设置日历的年月份显示范围，[范围开始，范围结束]。TS 类型：`Array<CalendarValue>` | N
range | Array | - | 用于设置日历的年月份显示范围，[范围开始，范围结束]。示例一：`['2018-08', '2028-04']`。示例二：`[new Date(2018, 8), new Date(2028, 4)]`。传入列表的两项均能被`dayjs`正常解析时才能使指定的日历范围生效，仅有一项正常解析时则为仅指定日历范围上限或下限。TS 类型：`Array<CalendarValue>` `type CalendarValue = string \| Date`。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
theme | String | full | 日历风格。可选项：full/card | N
value | String / Array / Date | - | 当前高亮的日期。TS 类型：`CalendarValue \| CalendarValue[]` `type CalendarValue = string \| Date`。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
week | TNode | - | 用于自定义日历星期呈现方式。CalendarWeek.day 表示当前是星期几。示例一：['周一', '周二', '周三', '周四', '周五', '星期六', '星期天']。示例二：`({ day }) => '周' + day`。TS 类型：`Array<string> \| TNode<CalendarWeek>` `interface CalendarWeek { day: WeekDay }` `type WeekDay = 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7`。[通用类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
Expand All @@ -30,9 +30,17 @@ onCellRightClick | Function | | TS 类型：`(options: { cell: CalendarCell; e:
onControllerChange | Function | | TS 类型：`(options: ControllerOptions) => void`<br/>右上角控件组选中值有变化的时候触发。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts)。<br/>`interface ControllerOptions { filterDate: Date; formattedFilterDate: string; mode: string; isShowWeekend: boolean }`<br/> | N
onMonthChange | Function | | TS 类型：`(options: { month: string; year: string }) => void`<br/>月份切换时触发 | N

### CalendarInstanceFunctions 组件实例方法

名称 | 参数 | 返回值 | 描述
-- | -- | -- | --
className | String | - | 类名 | N
style | Object | - | 样式，TS 类型：`React.CSSProperties` | N
toCurrent | \- | \- | 跳转到今天

### CalendarController

名称 | 类型 | 默认值 | 说明 | 必传
名称 | 类型 | 默认值 | 描述 | 必传
-- | -- | -- | -- | --
current | Object | - | “今天(本月)”按钮控制器。TS 类型：`{ visible?: boolean; currentDayButtonProps?: ButtonProps; currentMonthButtonProps?: ButtonProps }`，[Button API Documents](./button?tab=api)。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/calendar/type.ts) | N
disabled | Boolean | false | 是否禁用右上角控制器 | N
Expand All @@ -43,12 +51,12 @@ year | Object | - | 日历年份控制器。TS 类型：`{ visible?: boolean; se

### CalendarCell

名称 | 类型 | 默认值 | 说明 | 必传
名称 | 类型 | 默认值 | 描述 | 必传
-- | -- | -- | -- | --
belongTo | Number | - | 用于表示日期单元格属于哪一个月份。值为 0 表示是当前日历显示的月份中的日期，值为 -1 表示是上个月的，值为 1 表示是下个月的（日历展示维度是“月”时有值） | N
date | Object | - | 日历单元格日期。TS 类型：`Date` | N
day | Number | - | 日期单元格对应的星期，值为 1~7，表示周一到周日。（日历展示维度是“月”时有值） | N
formattedDate | String | - | 日历单元格日期字符串（输出日期的格式和 format 有关） | N
isCurrent | Boolean | - | 日期单元格是否为当前高亮日期或高亮月份 | N
weekOrder | Number | - | 日期在本月的第几周（日历展示维度是“月”时有值） | N
`ControllerOptions` | \- | - | 继承 `ControllerOptions` 中的全部 API | N
`ControllerOptions` | \- | - | 继承 `ControllerOptions` 中的全部属性 | N
10 changes: 9 additions & 1 deletion packages/products/tdesign-react/packages/components/calendar/type.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ export interface TdCalendarProps {
*/
preventCellContextmenu?: boolean;
/**
* 用于设置日历的年月份显示范围，[范围开始，范围结束]
* 用于设置日历的年月份显示范围，[范围开始，范围结束]。示例一：`['2018-08', '2028-04']`。示例二：`[new Date(2018, 8), new Date(2028, 4)]`。传入列表的两项均能被`dayjs`正常解析时才能使指定的日历范围生效，仅有一项正常解析时则为仅指定日历范围上限或下限
*/
range?: Array<CalendarValue>;
/**
Expand Down Expand Up @@ -107,6 +107,14 @@ export interface TdCalendarProps {
onMonthChange?: (options: { month: string; year: string }) => void;
}

/** 组件实例方法 */
export interface CalendarInstanceFunctions {
/**
* 跳转到今天
*/
toCurrent?: () => void;
}

export interface CalendarController {
/**
* “今天(本月)”按钮控制器
Expand Down
Loading