docs(Form): update api docs

packages/products/tdesign-miniprogram/src/form/form-item-props.ts → packages/products/tdesign-miniprogram/src/form-item/props.ts

@@ -6,6 +6,11 @@
 
 import { TdFormItemProps } from './type';
 const props: TdFormItemProps = {
+  /** 是否显示右侧箭头 */
+  arrow: {
+    type: Boolean,
+    value: false,
+  },
   /** label 原生属性 */
   for: {
     type: String,
@@ -15,6 +20,11 @@ const props: TdFormItemProps = {
   help: {
     type: String,
   },
+  /** 字段标签名称 */
+  label: {
+    type: String,
+    value: '',
+  },
   /** 表单字段标签对齐方式：左对齐、右对齐、顶部对齐。默认使用 Form 的对齐方式，优先级高于 Form.labelAlign */
   labelAlign: {
     type: String,

packages/products/tdesign-miniprogram/src/form-item/type.ts

@@ -0,0 +1,82 @@
+/* eslint-disable */
+
+/**
+ * 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
+ * */
+
+export interface TdFormItemProps {
+  /**
+   * 是否显示右侧箭头
+   * @default false
+   */
+  arrow?: {
+    type: BooleanConstructor;
+    value?: boolean;
+  };
+  /**
+   * label 原生属性
+   * @default ''
+   */
+  for?: {
+    type: StringConstructor;
+    value?: string;
+  };
+  /**
+   * 表单项说明内容
+   */
+  help?: {
+    type: StringConstructor;
+    value?: string;
+  };
+  /**
+   * 字段标签名称
+   * @default ''
+   */
+  label?: {
+    type: StringConstructor;
+    value?: string;
+  };
+  /**
+   * 表单字段标签对齐方式：左对齐、右对齐、顶部对齐。默认使用 Form 的对齐方式，优先级高于 Form.labelAlign
+   */
+  labelAlign?: {
+    type: StringConstructor;
+    value?: 'left' | 'right' | 'top';
+  };
+  /**
+   * 可以整体设置标签宽度，优先级高于 Form.labelWidth
+   */
+  labelWidth?: {
+    type: null;
+    value?: string | number;
+  };
+  /**
+   * 表单字段名称
+   * @default ''
+   */
+  name?: {
+    type: StringConstructor;
+    value?: string;
+  };
+  /**
+   * 是否显示必填符号（*），优先级高于 Form.requiredMark
+   */
+  requiredMark?: {
+    type: BooleanConstructor;
+    value?: boolean;
+  };
+  /**
+   * 表单字段校验规则
+   */
+  rules?: {
+    type: ArrayConstructor;
+    value?: Array<FormRule>;
+  };
+  /**
+   * 校验不通过时，是否显示错误提示信息，优先级高于 `Form.showErrorMessage`
+   */
+  showErrorMessage?: {
+    type: BooleanConstructor;
+    value?: boolean;
+  };
+}

packages/products/tdesign-miniprogram/src/form/README.en-US.md

@@ -2,24 +2,26 @@
 
 ## API
 
+
 ### Form Props
 
 name | type | default | description | required
 -- | -- | -- | -- | --
 style | Object | - | CSS(Cascading Style Sheets) | N
 custom-style | Object | - | CSS(Cascading Style Sheets)，used to set style on virtual component | N
 colon | Boolean | false | \- | N
+data | Object | {} | Typescript：`FormData` | N
 disabled | Boolean | undefined | \- | N
 error-message | Object | - | Typescript：`FormErrorMessage` | N
 label-align | String | right | options: left/right/top | N
 label-width | String / Number | '81px' | \- | N
-prevent-submit-default | Boolean | true | \- | N
+readonly | Boolean | undefined | \- | N
 required-mark | Boolean | undefined | \- | N
+required-mark-position | String | - | Display position of required symbols。options: left/right | N
 reset-type | String | empty | options: empty/initial | N
 rules | Object | - | Typescript：`FormRules<FormData>` `type FormRules<T extends Data = any> = { [field in keyof T]?: Array<FormRule> }`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts) | N
 scroll-to-first-error | String | - | options: ''/smooth/auto | N
 show-error-message | Boolean | true | \- | N
-status-icon | Boolean / Slot | undefined | [see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/src/common/common.ts) | N
 submit-with-warning-message | Boolean | false | \- | N
 
 ### Form Events
@@ -28,13 +30,17 @@ name | params | description
 -- | -- | --
 reset | `(detail: { e?: FormResetEvent })` | \-
 submit | `(context: SubmitContext<FormData>)` | [see more ts definition](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`interface SubmitContext<T extends Data = Data> { e?: FormSubmitEvent; validateResult: FormValidateResult<T>; firstError?: string; fields?: any }`<br/><br/>`type FormValidateResult<T> = boolean \| ValidateResultObj<T>`<br/><br/>`type ValidateResultObj<T> = { [key in keyof T]: boolean \| ValidateResultList }`<br/><br/>`type ValidateResultList = Array<AllValidateResult>`<br/><br/>`type AllValidateResult = CustomValidateObj \| ValidateResultType`<br/><br/>`interface ValidateResultType extends FormRule { result: boolean }`<br/><br/>`type ValidateResult<T> = { [key in keyof T]: boolean \| ErrorList }`<br/><br/>`type ErrorList = Array<FormRule>`<br/>
+validate | `(result: ValidateResultContext<FormData>)` | [see more ts definition](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`type ValidateResultContext<T extends Data> = Omit<SubmitContext<T>, 'e'>`<br/>
 
 ### FormInstanceFunctions 组件实例方法
 
 name | params | return | description
 -- | -- | -- | --
 clear-validate | `(fields?: Array<keyof FormData>)` | \- | required
 reset | `(params?: FormResetParams<FormData>)` | \- | required。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
+set-validate-message | `(message: FormValidateMessage<FormData>)` | \- | required。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`type FormValidateMessage<FormData> = { [field in keyof FormData]: FormItemValidateMessage[] }`<br/><br/>`interface FormItemValidateMessage { type: 'warning' \| 'error'; message: string }`<br/>
+submit | `(params?: { showErrorMessage?: boolean })` | \- | required
+validate | `(params?: FormValidateParams)` | `Promise<FormValidateResult<FormData>>` | required。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`interface FormValidateParams { fields?: Array<string>; showErrorMessage?: boolean; trigger?: ValidateTriggerType }`<br/><br/>`type ValidateTriggerType = 'blur' \| 'change' \| 'submit' \| 'all'`<br/>
 
 
 ### FormItem Props
@@ -43,8 +49,10 @@ name | type | default | description | required
 -- | -- | -- | -- | --
 style | Object | - | CSS(Cascading Style Sheets) | N
 custom-style | Object | - | CSS(Cascading Style Sheets)，used to set style on virtual component | N
+arrow | Boolean | false | \- | N
 for | String | - | \- | N
 help | String / Slot | - | [see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/src/common/common.ts) | N
+label | String / Slot | '' | [see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/src/common/common.ts) | N
 label-align | String | - | options: left/right/top | N
 label-width | String / Number | - | \- | N
 name | String | - | \- | N

packages/products/tdesign-miniprogram/src/form/README.md

@@ -2,24 +2,26 @@
 
 ## API
 
+
 ### Form Props
 
 名称 | 类型 | 默认值 | 描述 | 必传
 -- | -- | -- | -- | --
 style | Object | - | 样式 | N
 custom-style | Object | - | 样式，一般用于开启虚拟化组件节点场景 | N
 colon | Boolean | false | 是否在表单标签字段右侧显示冒号 | N
+data | Object | {} | 表单数据。TS 类型：`FormData` | N
 disabled | Boolean | undefined | 是否禁用整个表单 | N
 error-message | Object | - | 表单错误信息配置，示例：`{ idcard: '请输入正确的身份证号码', max: '字符长度不能超过 ${max}' }`。TS 类型：`FormErrorMessage` | N
 label-align | String | right | 表单字段标签对齐方式：左对齐、右对齐、顶部对齐。可选项：left/right/top | N
 label-width | String / Number | '81px' | 可以整体设置label标签宽度，默认为81px | N
-prevent-submit-default | Boolean | true | 是否阻止表单提交默认事件（表单提交默认事件会刷新页面），设置为 `true` 可以避免刷新 | N
+readonly | Boolean | undefined | 是否整个表单只读 | N
 required-mark | Boolean | undefined | 是否显示必填符号（*），默认显示 | N
+required-mark-position | String | - | 表单必填符号（*）显示位置。可选项：left/right | N
 reset-type | String | empty | 重置表单的方式，值为 empty 表示重置表单为空，值为 initial 表示重置表单数据为初始值。可选项：empty/initial | N
 rules | Object | - | 表单字段校验规则。TS 类型：`FormRules<FormData>` `type FormRules<T extends Data = any> = { [field in keyof T]?: Array<FormRule> }`。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts) | N
 scroll-to-first-error | String | - | 表单校验不通过时，是否自动滚动到第一个校验不通过的字段，平滑滚动或是瞬间直达。值为空则表示不滚动。可选项：''/smooth/auto | N
 show-error-message | Boolean | true | 校验不通过时，是否显示错误提示信息，统一控制全部表单项。如果希望控制单个表单项，请给 FormItem 设置该属性 | N
-status-icon | Boolean / Slot | undefined | 校验状态图标，值为 `true` 显示默认图标，默认图标有 成功、失败、警告 等，不同的状态图标不同。`statusIcon` 值为 `false`，不显示图标。`statusIcon` 值类型为渲染函数，则可以自定义右侧状态图标。[通用类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/src/common/common.ts) | N
 submit-with-warning-message | Boolean | false | 【讨论中】当校验结果只有告警信息时，是否触发 `submit` 提交事件 | N
 
 ### Form Events
@@ -28,13 +30,17 @@ submit-with-warning-message | Boolean | false | 【讨论中】当校验结果
 -- | -- | --
 reset | `(detail: { e?: FormResetEvent })` | 表单重置时触发
 submit | `(context: SubmitContext<FormData>)` | 表单提交时触发。其中 `context.validateResult` 表示校验结果，`context.firstError` 表示校验不通过的第一个规则提醒。`context.validateResult` 值为 `true` 表示校验通过；如果校验不通过，`context.validateResult` 值为校验结果列表。<br />【注意】⚠️ 默认情况，输入框按下 Enter 键会自动触发提交事件，如果希望禁用这个默认行为，可以给输入框添加  enter 事件，并在事件中设置 `e.preventDefault()`。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`interface SubmitContext<T extends Data = Data> { e?: FormSubmitEvent; validateResult: FormValidateResult<T>; firstError?: string; fields?: any }`<br/><br/>`type FormValidateResult<T> = boolean \| ValidateResultObj<T>`<br/><br/>`type ValidateResultObj<T> = { [key in keyof T]: boolean \| ValidateResultList }`<br/><br/>`type ValidateResultList = Array<AllValidateResult>`<br/><br/>`type AllValidateResult = CustomValidateObj \| ValidateResultType`<br/><br/>`interface ValidateResultType extends FormRule { result: boolean }`<br/><br/>`type ValidateResult<T> = { [key in keyof T]: boolean \| ErrorList }`<br/><br/>`type ErrorList = Array<FormRule>`<br/>
+validate | `(result: ValidateResultContext<FormData>)` | 校验结束后触发，result 值为 true 表示校验通过；如果校验不通过，result 值为校验结果列表。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`type ValidateResultContext<T extends Data> = Omit<SubmitContext<T>, 'e'>`<br/>
 
 ### FormInstanceFunctions 组件实例方法
 
 名称 | 参数 | 返回值 | 描述
 -- | -- | -- | --
 clear-validate | `(fields?: Array<keyof FormData>)` | \- | 必需。清空校验结果。可使用 fields 指定清除部分字段的校验结果，fields 值为空则表示清除所有字段校验结果。清除邮箱校验结果示例：`clearValidate(['email'])`
 reset | `(params?: FormResetParams<FormData>)` | \- | 必需。重置表单，表单里面没有重置按钮`<button type=\"reset\" />`时可以使用该方法，默认重置全部字段为空，该方法会触发 `reset` 事件。<br />如果表单属性 `resetType='empty'` 或者 `reset.type='empty'` 会重置为空；<br />如果表单属性 `resetType='initial'` 或者 `reset.type='initial'` 会重置为表单初始值。<br />`reset.fields` 用于设置具体重置哪些字段，示例：`reset({ type: 'initial', fields: ['name', 'age'] })`。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
+set-validate-message | `(message: FormValidateMessage<FormData>)` | \- | 必需。设置自定义校验结果，如远程校验信息直接呈现。注意需要在组件挂载结束后使用该方法。`FormData` 指表单数据泛型。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`type FormValidateMessage<FormData> = { [field in keyof FormData]: FormItemValidateMessage[] }`<br/><br/>`interface FormItemValidateMessage { type: 'warning' \| 'error'; message: string }`<br/>
+submit | `(params?: { showErrorMessage?: boolean })` | \- | 必需。提交表单，表单里面没有提交按钮`<button type=\"submit\" />`时可以使用该方法。`showErrorMessage` 表示是否在提交校验不通过时显示校验不通过的原因，默认显示。该方法会触发 `submit` 事件
+validate | `(params?: FormValidateParams)` | `Promise<FormValidateResult<FormData>>` | 必需。校验函数，包含错误文本提示等功能。泛型 `FormData` 表示表单数据 TS 类型。<br/>【关于参数】`params.fields` 表示校验字段，如果设置了 `fields`，本次校验将仅对这些字段进行校验。`params.trigger` 表示本次触发校验的范围，'params.trigger = blur' 表示只触发校验规则设定为 trigger='blur' 的字段，'params.trigger = change' 表示只触发校验规则设定为 trigger='change' 的字段，默认触发全范围校验。`params.showErrorMessage` 表示校验结束后是否显示错误文本提示，默认显示。<br />【关于返回值】返回值为 true 表示校验通过；如果校验不通过，返回值为校验结果列表。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/form/type.ts)。<br/>`interface FormValidateParams { fields?: Array<string>; showErrorMessage?: boolean; trigger?: ValidateTriggerType }`<br/><br/>`type ValidateTriggerType = 'blur' \| 'change' \| 'submit' \| 'all'`<br/>
 
 
 ### FormItem Props
@@ -43,8 +49,10 @@ reset | `(params?: FormResetParams<FormData>)` | \- | 必需。重置表单，
 -- | -- | -- | -- | --
 style | Object | - | 样式 | N
 custom-style | Object | - | 样式，一般用于开启虚拟化组件节点场景 | N
+arrow | Boolean | false | 是否显示右侧箭头 | N
 for | String | - | label 原生属性 | N
 help | String / Slot | - | 表单项说明内容。[通用类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/src/common/common.ts) | N
+label | String / Slot | '' | 字段标签名称。[通用类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/src/common/common.ts) | N
 label-align | String | - | 表单字段标签对齐方式：左对齐、右对齐、顶部对齐。默认使用 Form 的对齐方式，优先级高于 Form.labelAlign。可选项：left/right/top | N
 label-width | String / Number | - | 可以整体设置标签宽度，优先级高于 Form.labelWidth | N
 name | String | - | 表单字段名称 | N

packages/products/tdesign-miniprogram/src/form/props.ts

@@ -11,6 +11,11 @@ const props: TdFormProps = {
     type: Boolean,
     value: false,
   },
+  /** 表单数据 */
+  data: {
+    type: Object,
+    value: {},
+  },
   /** 是否禁用整个表单 */
   disabled: {
     type: null,
@@ -30,16 +35,20 @@ const props: TdFormProps = {
     type: null,
     value: '81px',
   },
-  /** 是否阻止表单提交默认事件（表单提交默认事件会刷新页面），设置为 `true` 可以避免刷新 */
-  preventSubmitDefault: {
-    type: Boolean,
-    value: true,
+  /** 是否整个表单只读 */
+  readonly: {
+    type: null,
+    value: undefined,
   },
   /** 是否显示必填符号（*），默认显示 */
   requiredMark: {
     type: null,
     value: undefined,
   },
+  /** 表单必填符号（*）显示位置 */
+  requiredMarkPosition: {
+    type: String,
+  },
   /** 重置表单的方式，值为 empty 表示重置表单为空，值为 initial 表示重置表单数据为初始值 */
   resetType: {
     type: String,
@@ -58,11 +67,6 @@ const props: TdFormProps = {
     type: Boolean,
     value: true,
   },
-  /** 校验状态图标，值为 `true` 显示默认图标，默认图标有 成功、失败、警告 等，不同的状态图标不同。`statusIcon` 值为 `false`，不显示图标。`statusIcon` 值类型为渲染函数，则可以自定义右侧状态图标 */
-  statusIcon: {
-    type: null,
-    value: undefined,
-  },
   /** 【讨论中】当校验结果只有告警信息时，是否触发 `submit` 提交事件 */
   submitWithWarningMessage: {
     type: Boolean,