docs(calendar): update api docs

src/calendar/calendar.en-US.md

@@ -0,0 +1,25 @@
+:: BASE_DOC ::
+
+## API
+### Calendar Props
+
+name | type | default | description | required
+-- | -- | -- | -- | --
+confirmBtn | String / Object / Slot / Function | '' | Typescript：`string | TNode | ButtonProps | null`，[Button API Documents](./button?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/calendar/type.ts) | N
+firstDayOfWeek | Number | 7 | \- | N
+format | Function | - | Typescript：`(day: TDate) => TDate` `type TDateType = 'selected' | 'disabled' | 'start' | 'centre' | 'end'; ` `interface TDate { date: Date; day: number; type: TDateType; className: string; }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/calendar/type.ts) | N
+maxDate | Number / Date | - | Typescript：`number | Date` | N
+minDate | Number / Date | - | Typescript：`number | Date` | N
+title | String / Slot / Function | - | Typescript：`string | TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
+type | String | 'single' | options：single/multiple/range | N
+value | Number / Array / Date | - | Typescript：`number | Date | TCalendarValue[] ` `type TCalendarValue = number | Date`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/calendar/type.ts) | N
+visible | Boolean | false | \- | N
+onConfirm | Function |  | Typescript：`(value: Date) => void`<br/> | N
+onSelect | Function |  | Typescript：`(value: Date) => void`<br/> | N
+
+### Calendar Events
+
+name | params | description
+-- | -- | --
+confirm | `(value: Date)` | \-
+select | `(value: Date)` | \-

src/calendar/calendar.md

@@ -1,21 +1,25 @@
 :: BASE_DOC ::
 
 ## API
+### Calendar Props
 
-### Calendar Events
-
-名称 | 参数 | 描述
--- | -- | --
-modelValue | Boolean | false | 控制日历显示与隐藏 | Y
-bgColor | String |  #0053DB | 按钮和单元格背景颜色 | N
-confirmBtn | String |  确认 | 确认按钮文案 | N
-head |  Slot / Function |  - | 头部插槽（左上角处，默认不显示任何内容），TS 类型：`string | TNode` [通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
-cell |  Slot / Function |  今天日期 | 自定义单元格 类型：`string | TNode` [通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
-value | String / Date |  new Date | 当前高亮的日期，默认今天 | N
+名称 | 类型 | 默认值 | 说明 | 必传
+-- | -- | -- | -- | --
+confirmBtn | String / Object / Slot / Function | '' | 确认按钮。值为 null 则不显示确认按钮。值类型为字符串，则表示自定义按钮文本，值类型为 Object 则表示透传 Button 组件属性。。TS 类型：`string | TNode | ButtonProps | null`，[Button API Documents](./button?tab=api)。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/calendar/type.ts) | N
+firstDayOfWeek | Number | 7 | 第一天从星期几开始，默认周日 | N
+format | Function | - | 用于格式化日期的函数。TS 类型：`(day: TDate) => TDate` `type TDateType = 'selected' | 'disabled' | 'start' | 'centre' | 'end'; ` `interface TDate { date: Date; day: number; type: TDateType; className: string; }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/calendar/type.ts) | N
+maxDate | Number / Date | - | 最大可选的日期，不传则默认半年后。TS 类型：`number | Date` | N
+minDate | Number / Date | - | 最小可选的日期，不传则默认今天。TS 类型：`number | Date` | N
+title | String / Slot / Function | - | 标题，不传默认为“请选择日期”。TS 类型：`string | TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-vue/blob/develop/src/common.ts) | N
+type | String | 'single' | 日历的选择类型，singe = 单选；multiple = 多选; range = 区间选择。可选项：single/multiple/range | N
+value | Number / Array / Date | - | 当前选择的日期，不传则默认今天，当 type = multiple 或 range 时传入数组。TS 类型：`number | Date | TCalendarValue[] ` `type TCalendarValue = number | Date`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-vue/tree/develop/src/calendar/type.ts) | N
+visible | Boolean | false | 是否显示日历 | N
+onConfirm | Function |  | TS 类型：`(value: Date) => void`<br/>点击确认按钮时触发 | N
+onSelect | Function |  | TS 类型：`(value: Date) => void`<br/>选择日期时触发 | N
 
 ### Calendar Events
 
 名称 | 参数 | 描述
 -- | -- | --
-cell-click | cell: `type CalendarCell = {year: number;month: number;day: number;}`| 点击单元格触发 |
-confirm | dateValue: `type CalendarValue = {year: number;month: number;day: number;week: number;date: string;isToday: boolean;}` | 点击确认按钮触发 |
+confirm | `(value: Date)` | 点击确认按钮时触发
+select | `(value: Date)` | 选择日期时触发

src/calendar/props.ts

@@ -6,64 +6,51 @@
 
 import { TdCalendarProps } from './type';
 import { PropType } from 'vue';
-import { timestamp } from '@vueuse/core';
 
 export default {
-  /**
-   * 控制日历显示隐藏
-   */
-  visible: {
-    type: Boolean,
-  },
-  // 按钮颜色
-  bgColor: {
-    type: String,
-    default: '#0053DB',
-  },
-  /**
-   * 确认按钮
-   */
+  /** 确认按钮。值为 null 则不显示确认按钮。值类型为字符串，则表示自定义按钮文本，值类型为 Object 则表示透传 Button 组件属性。 */
   confirmBtn: {
-    type: String,
-    default: '确认',
+    type: [String, Object, Function] as PropType<TdCalendarProps['confirmBtn']>,
+    default: '',
   },
-  /**
-   * 第一天从星期几开始，仅在日历展示维度为月份时（mode = month）有效。默认为 1
-   */
+  /** 第一天从星期几开始，默认周日 */
   firstDayOfWeek: {
     type: Number,
+    default: 7,
   },
-  /**
-   * 头部插槽（左上角处，默认不显示任何内容）
-   */
-  title: {
-    type: String,
-  },
-  /**
-   * 当前高亮的日期
-   */
-  value: {
-    type: Number,
-  },
-  minDate: {
-    type: Number,
-    default: null,
+  /** 用于格式化日期的函数 */
+  format: {
+    type: Function as PropType<TdCalendarProps['format']>,
   },
+  /** 最大可选的日期，不传则默认半年后 */
   maxDate: {
-    type: Number,
-    default: null,
+    type: [Number, Date] as PropType<TdCalendarProps['maxDate']>,
   },
-  onSelect: {
-    type: Function,
-  },
-  onConfirm: {
-    type: Function,
+  /** 最小可选的日期，不传则默认今天 */
+  minDate: {
+    type: [Number, Date] as PropType<TdCalendarProps['minDate']>,
   },
-  format: {
-    type: Function,
+  /** 标题，不传默认为“请选择日期” */
+  title: {
+    type: [String, Function] as PropType<TdCalendarProps['title']>,
   },
+  /** 日历的选择类型，singe = 单选；multiple = 多选; range = 区间选择 */
   type: {
-    type: String,
-    default: 'single',
-  },
+    type: String as PropType<TdCalendarProps['type']>,
+    default: 'single' as TdCalendarProps['type'],
+    validator(val: TdCalendarProps['type']): boolean {
+      if (!val) return true;
+      return ['single', 'multiple', 'range'].includes(val);
+    },
+  },
+  /** 当前选择的日期，不传则默认今天，当 type = multiple 或 range 时传入数组 */
+  value: {
+    type: [Number, Array, Date] as PropType<TdCalendarProps['value']>,
+  },
+  /** 是否显示日历 */
+  visible: Boolean,
+  /** 点击确认按钮时触发 */
+  onConfirm: Function as PropType<TdCalendarProps['onConfirm']>,
+  /** 选择日期时触发 */
+  onSelect: Function as PropType<TdCalendarProps['onSelect']>,
 };

src/calendar/type.ts

@@ -3,43 +3,68 @@
 /**
  * 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
  * */
+
+import { ButtonProps } from '../button';
+import { TNode } from '../common';
+
 export interface TdCalendarProps {
   /**
-   * 控制日历显示隐藏
+   * 确认按钮。值为 null 则不显示确认按钮。值类型为字符串，则表示自定义按钮文本，值类型为 Object 则表示透传 Button 组件属性。
+   * @default ''
    */
-  modelValue: boolean;
+  confirmBtn?: string | TNode | ButtonProps | null;
   /**
-   * 背景颜色
+   * 第一天从星期几开始，默认周日
+   * @default 7
    */
-  bgColor?: string;
-
+  firstDayOfWeek?: number;
   /**
-   * 确认按钮
+   * 用于格式化日期的函数
    */
-  confirmBtn?: string;
+  format?: (day: TDate) => TDate;
   /**
-   * 第一天从星期几开始，仅在日历展示维度为月份时（mode = month）有效。默认为 1
+   * 最大可选的日期，不传则默认半年后
    */
-  firstDayOfWeek?: number;
+  maxDate?: number | Date;
   /**
-   * 头部插槽（左上角处，默认不显示任何内容）
+   * 最小可选的日期，不传则默认今天
    */
-  title?: string;
+  minDate?: number | Date;
   /**
-   * 当前高亮的日期
+   * 标题，不传默认为“请选择日期”
    */
-  value?: CalendarValue;
+  title?: string | TNode;
+  /**
+   * 日历的选择类型，singe = 单选；multiple = 多选; range = 区间选择
+   * @default 'single'
+   */
+  type?: 'single' | 'multiple' | 'range';
+  /**
+   * 当前选择的日期，不传则默认今天，当 type = multiple 或 range 时传入数组
+   */
+  value?: number | Date | TCalendarValue[];
+  /**
+   * 是否显示日历
+   * @default false
+   */
+  visible?: boolean;
+  /**
+   * 点击确认按钮时触发
+   */
+  onConfirm?: (value: Date) => void;
+  /**
+   * 选择日期时触发
+   */
+  onSelect?: (value: Date) => void;
 }
 
-export interface DateCellDescription {
-  date: Date;
-  label: string;
-}
+export type TDateType = 'selected' | 'disabled' | 'start' | 'centre' | 'end';
 
-export type CalendarCell = {
-  year: number;
-  month: number;
+export interface TDate {
+  date: Date;
   day: number;
-};
+  type: TDateType;
+  className: string;
+}
 
-export type CalendarValue = number | number[];
+export type TCalendarValue = number | Date;