docs(calendar): update range api desc (#791)

* docs(calendar): update `range` api desc

* docs(calendar): add `CalendarValue` ts definition

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: shumuuu

db/TDesign.db

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

packages/products/tdesign-react/packages/components/calendar/calendar.en-US.md

@@ -3,7 +3,7 @@
 ## API
 ### Calendar Props
 
-名称 | 类型 | 默认值 | 说明 | 必传
+名称 | 类型 | 默认值 | 描述 | 必传
 -- | -- | -- | -- | --
 className | String | - | 类名 | N
 style | Object | - | 样式，TS 类型：`React.CSSProperties` | N
@@ -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
@@ -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
@@ -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

packages/products/tdesign-react/packages/components/calendar/calendar.md

@@ -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>;
   /**
@@ -107,6 +107,14 @@ export interface TdCalendarProps {
   onMonthChange?: (options: { month: string; year: string }) => void;
 }
 
+/** 组件实例方法 */
+export interface CalendarInstanceFunctions {
+  /**
+   * 跳转到今天
+   */
+  toCurrent?: () => void;
+}
+
 export interface CalendarController {
   /**
    * “今天(本月)”按钮控制器