From 40329b423d82076756122024eba0b2106bfbf49c Mon Sep 17 00:00:00 2001
From: anlyyao <anly_yaw@163.com>
Date: Mon, 20 Apr 2026 16:54:32 +0800
Subject: [PATCH 1/3] feat(Form): update interface FormInstanceFunctions

---
 db/TDesign.db                                 | Bin 1134592 -> 1134592 bytes
 .../src/form/form.en-US.md                    |   7 ++
 .../tdesign-mobile-react/src/form/form.md     |   7 ++
 .../tdesign-mobile-react/src/form/type.ts     |  40 ++++++++++
 .../packages/components/form/form.en-US.md    |   1 +
 .../packages/components/form/form.md          |   1 +
 .../packages/components/form/type.ts          |   4 +
 packages/scripts/api.json                     |  75 +++++++++++++++---
 8 files changed, 123 insertions(+), 12 deletions(-)

diff --git a/db/TDesign.db b/db/TDesign.db
index 83cdd707ee1873672d5242c802d1e635549f9cb1..9d8d75c3a4b3edba3a79d5aa74c7e7ba17a4d7e5 100644
GIT binary patch
delta 409
zcmZoz;M%ajb%Hb_*F+g-RxSp;vaZII))dCADNK{98HJ{QuV!jx6xv=}!xaA&$URWT
ztl7?1#0<nNK+FonY}?t2*q=u+3bnsG!w$q8+uxnxycY=MpOxbRV(#r{<#<ein%kL0
zc!8J?i21iOiwH34u=z6WVBqze{wI+yVtQB;zu5K)2LTNxCcXpP7dZ*s=4N!8Ugsy^
z#+Lc?rMsZw_EUZWRu7r^S+-7RHxQI%V%fS~(Sfs{rM@v~k)jj}qbQ>xBQI~GHUp=x
zv9Tos11ASB2QLE$NVAYzeo-z<dTL2nVoqjCVo9oRYH@L5daA;UzU@!@r#)M+@a3wW
z=es9An>XkEo}Q<BC%@Rx{Cvs^1xy_pnhMXRZ+o$S%G25No^>`no74G>2T8ZabosAL
za<-aA21aJO1}3^j1_}liR;ET)M#fl#9E*w)D{Vk-3o6Y?wNt23D9g`G**@D;FjWcw
D$LN#P

delta 197
zcmZoz;M%ajb%Hb_(?l6(Rwf3$HqFMA))dCADNK{98JVVkuV!jxWZGU^!xaB@`u;Lz
zt#-B|W*}w(Vpbq#+s;<R{yd72sr}s<b|B{1{_YIty};?qq`8XQ?d7?En0vduJkQ}T
zKqbr~yg<wc#QfWtMFbdi*nF6FF!1_K|C7iUF+Hq_Uu=7YgMbDT6DRZbMNR^@xfuhd
q*ZB#!O>gMo=h}YGPr&RUGau{h>FfrAvfC8{xXW3$&o&iIl>z`Z$Ug}H

diff --git a/packages/products/tdesign-mobile-react/src/form/form.en-US.md b/packages/products/tdesign-mobile-react/src/form/form.en-US.md
index 8f392243f..33d8aa845 100644
--- a/packages/products/tdesign-mobile-react/src/form/form.en-US.md
+++ b/packages/products/tdesign-mobile-react/src/form/form.en-US.md
@@ -36,7 +36,14 @@ name | params | return | description
 className | String | - | className of component | N
 style | Object | - | CSS(Cascading Style Sheets)，Typescript: `React.CSSProperties` | N
 clearValidate | `(fields?: Array<keyof FormData>)` | \- | required
+currentElement | \- | `HTMLFormElement` | \-
+getCurrentElement | \- | `HTMLFormElement` | \-
+getFieldValue | `(field: NamePath) ` | `unknown` | required
+getFieldsValue | `(nameList: string[] \| boolean)` | `getFieldsValue<FormData>` | required。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface getFieldsValue<T>{ (nameList: true): T; (nameList: any[]): Record<keyof T, unknown>;}`<br/>
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| voi` | required
 reset | `(params?: FormResetParams<FormData>)` | \- | required。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
+setFields | `(fields: FieldData[])` | \- | required。Typescript: `(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)
+setFieldsValue | `(field: Data)` | \- | required
 setValidateMessage | `(message: FormValidateMessage<FormData>)` | \- | required。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/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-mobile-react/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/>
diff --git a/packages/products/tdesign-mobile-react/src/form/form.md b/packages/products/tdesign-mobile-react/src/form/form.md
index 18d352006..a958b34c5 100644
--- a/packages/products/tdesign-mobile-react/src/form/form.md
+++ b/packages/products/tdesign-mobile-react/src/form/form.md
@@ -36,7 +36,14 @@ onValuesChange | Function |  | TS 类型：`(changedValues: Record<string, unkno
 className | String | - | 类名 | N
 style | Object | - | 样式，TS 类型：`React.CSSProperties` | N
 clearValidate | `(fields?: Array<keyof FormData>)` | \- | 必需。清空校验结果。可使用 fields 指定清除部分字段的校验结果，fields 值为空则表示清除所有字段校验结果。清除邮箱校验结果示例：`clearValidate(['email'])`
+currentElement | \- | `HTMLFormElement` | 获取 form dom 元素
+getCurrentElement | \- | `HTMLFormElement` | 获取 form dom 元素
+getFieldValue | `(field: NamePath) ` | `unknown` | 必需。获取单个字段值
+getFieldsValue | `(nameList: string[] \| boolean)` | `getFieldsValue<FormData>` | 必需。获取一组字段名对应的值，当调用 getFieldsValue(true) 时返回所有表单数据。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface getFieldsValue<T>{ (nameList: true): T; (nameList: any[]): Record<keyof T, unknown>;}`<br/>
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| voi` | 必需。获取校验结果，当调用 getValidateMessage() 时返回所有校验结果
 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-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
+setFields | `(fields: FieldData[])` | \- | 必需。设置多组字段状态。TS 类型：`(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)
+setFieldsValue | `(field: Data)` | \- | 必需。设置表单字段值
 setValidateMessage | `(message: FormValidateMessage<FormData>)` | \- | 必需。设置自定义校验结果，如远程校验信息直接呈现。注意需要在组件挂载结束后使用该方法。`FormData` 指表单数据泛型。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/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-mobile-react/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/>
diff --git a/packages/products/tdesign-mobile-react/src/form/type.ts b/packages/products/tdesign-mobile-react/src/form/type.ts
index 28db88e5b..38bc242f0 100644
--- a/packages/products/tdesign-mobile-react/src/form/type.ts
+++ b/packages/products/tdesign-mobile-react/src/form/type.ts
@@ -105,10 +105,38 @@ export interface FormInstanceFunctions<FormData extends Data = Data> {
    * 清空校验结果。可使用 fields 指定清除部分字段的校验结果，fields 值为空则表示清除所有字段校验结果。清除邮箱校验结果示例：`clearValidate(['email'])`
    */
   clearValidate: (fields?: Array<keyof FormData>) => void;
+  /**
+   * 获取 form dom 元素
+   */
+  currentElement?: () => HTMLFormElement;
+  /**
+   * 获取 form dom 元素
+   */
+  getCurrentElement?: () => HTMLFormElement;
+  /**
+   * 获取单个字段值
+   */
+  getFieldValue: (field: NamePath) => unknown;
+  /**
+   * 获取一组字段名对应的值，当调用 getFieldsValue(true) 时返回所有表单数据
+   */
+  getFieldsValue: (nameList: string[] | boolean) => getFieldsValue<FormData>;
+  /**
+   * 获取校验结果，当调用 getValidateMessage() 时返回所有校验结果
+   */
+  getValidateMessage: (fields?: Array<keyof FormData>) => Array<FormRule> | voi;
   /**
    * 重置表单，表单里面没有重置按钮`<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'] })`
    */
   reset: (params?: FormResetParams<FormData>) => void;
+  /**
+   * 设置多组字段状态
+   */
+  setFields: (fields: FieldData[]) => void;
+  /**
+   * 设置表单字段值
+   */
+  setFieldsValue: (field: Data) => void;
   /**
    * 设置自定义校验结果，如远程校验信息直接呈现。注意需要在组件挂载结束后使用该方法。`FormData` 指表单数据泛型
    */
@@ -355,11 +383,23 @@ export type ErrorList = Array<FormRule>;
 
 export type ValidateResultContext<T extends Data> = Omit<SubmitContext<T>, 'e'>;
 
+export interface getFieldsValue<T> {
+  (nameList: true): T;
+  (nameList: any[]): Record<keyof T, unknown>;
+}
+
 export interface FormResetParams<FormData> {
   type?: 'initial' | 'empty';
   fields?: Array<keyof FormData>;
 }
 
+export interface FieldData {
+  name: NamePath;
+  value?: unknown;
+  status?: string;
+  validateMessage?: { type?: string; message?: string };
+}
+
 export type FormValidateMessage<FormData> = { [field in keyof FormData]: FormItemValidateMessage[] };
 
 export interface FormItemValidateMessage {
diff --git a/packages/products/tdesign-react/packages/components/form/form.en-US.md b/packages/products/tdesign-react/packages/components/form/form.en-US.md
index dc85754cf..0627b532d 100644
--- a/packages/products/tdesign-react/packages/components/form/form.en-US.md
+++ b/packages/products/tdesign-react/packages/components/form/form.en-US.md
@@ -44,6 +44,7 @@ currentElement | \- | `HTMLFormElement` | \-
 getCurrentElement | \- | `HTMLFormElement` | \-
 getFieldValue | `(field: NamePath) ` | `unknown` | required
 getFieldsValue | `(nameList: string[] \| boolean)` | `getFieldsValue<FormData>` | required。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/form/type.ts)。<br/>`interface getFieldsValue<T>{ (nameList: true): T; (nameList: any[]): Record<keyof T, unknown>;}`<br/>
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| voi` | required
 reset | `(params?: FormResetParams<FormData>)` | \- | required。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
 setFields | `(fields: FieldData[])` | \- | required。Typescript: `(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/form/type.ts)
 setFieldsValue | `(field: Data)` | \- | required
diff --git a/packages/products/tdesign-react/packages/components/form/form.md b/packages/products/tdesign-react/packages/components/form/form.md
index bd0e707b9..7abcf5802 100644
--- a/packages/products/tdesign-react/packages/components/form/form.md
+++ b/packages/products/tdesign-react/packages/components/form/form.md
@@ -44,6 +44,7 @@ currentElement | \- | `HTMLFormElement` | 获取 form dom 元素
 getCurrentElement | \- | `HTMLFormElement` | 获取 form dom 元素
 getFieldValue | `(field: NamePath) ` | `unknown` | 必需。获取单个字段值
 getFieldsValue | `(nameList: string[] \| boolean)` | `getFieldsValue<FormData>` | 必需。获取一组字段名对应的值，当调用 getFieldsValue(true) 时返回所有表单数据。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/form/type.ts)。<br/>`interface getFieldsValue<T>{ (nameList: true): T; (nameList: any[]): Record<keyof T, unknown>;}`<br/>
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| voi` | 必需。获取校验结果，当调用 getValidateMessage() 时返回所有校验结果
 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-react/blob/develop/packages/components/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
 setFields | `(fields: FieldData[])` | \- | 必需。设置多组字段状态。TS 类型：`(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/form/type.ts)
 setFieldsValue | `(field: Data)` | \- | 必需。设置表单字段值
diff --git a/packages/products/tdesign-react/packages/components/form/type.ts b/packages/products/tdesign-react/packages/components/form/type.ts
index bec42090a..b1ad6ead2 100644
--- a/packages/products/tdesign-react/packages/components/form/type.ts
+++ b/packages/products/tdesign-react/packages/components/form/type.ts
@@ -138,6 +138,10 @@ export interface FormInstanceFunctions<FormData extends Data = Data> {
    * 获取一组字段名对应的值，当调用 getFieldsValue(true) 时返回所有表单数据
    */
   getFieldsValue: (nameList: string[] | boolean) => getFieldsValue<FormData>;
+  /**
+   * 获取校验结果，当调用 getValidateMessage() 时返回所有校验结果
+   */
+  getValidateMessage: (fields?: Array<keyof FormData>) => Array<FormRule> | voi;
   /**
    * 重置表单，表单里面没有重置按钮`<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'] })`
    */
diff --git a/packages/scripts/api.json b/packages/scripts/api.json
index 9be16cfc9..e5d487180 100644
--- a/packages/scripts/api.json
+++ b/packages/scripts/api.json
@@ -60663,7 +60663,8 @@
     {
       "id": 2941,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 4,
@@ -60691,7 +60692,8 @@
       "support_default_value": 0,
       "field_category_text": "Functions",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Function"
@@ -60700,7 +60702,8 @@
     {
       "id": 1706499223,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 4,
@@ -60728,7 +60731,8 @@
       "support_default_value": 0,
       "field_category_text": "Functions",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Function"
@@ -60737,7 +60741,8 @@
     {
       "id": 1068,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 4,
@@ -60765,7 +60770,8 @@
       "support_default_value": 0,
       "field_category_text": "Functions",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Function"
@@ -60774,7 +60780,8 @@
     {
       "id": 2272,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 4,
@@ -60802,7 +60809,47 @@
       "support_default_value": 0,
       "field_category_text": "Functions",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
+      ],
+      "field_type_text": [
+        "Function"
+      ]
+    },
+    {
+      "id": 1776675143,
+      "platform_framework": [
+        "2",
+        "16"
+      ],
+      "component": "Form",
+      "field_category": 4,
+      "field_name": "getValidateMessage",
+      "field_type": [
+        "32"
+      ],
+      "field_default_value": "",
+      "field_enum": "",
+      "field_desc_zh": "获取校验结果，当调用 getValidateMessage() 时返回所有校验结果",
+      "field_desc_en": null,
+      "field_required": 1,
+      "event_input": "(fields?: Array<keyof FormData>)",
+      "create_time": "2026-04-20 08:52:23",
+      "update_time": "2026-04-20 08:52:23",
+      "event_output": "Array<FormRule> | void",
+      "custom_field_type": null,
+      "syntactic_sugar": null,
+      "readonly": 1,
+      "html_attribute": 0,
+      "trigger_elements": "",
+      "deprecated": 0,
+      "version": "",
+      "test_description": null,
+      "support_default_value": 0,
+      "field_category_text": "Functions",
+      "platform_framework_text": [
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Function"
@@ -60854,7 +60901,8 @@
     {
       "id": 1492,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 4,
@@ -60882,7 +60930,8 @@
       "support_default_value": 0,
       "field_category_text": "Functions",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Function"
@@ -60891,7 +60940,8 @@
     {
       "id": 1067,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 4,
@@ -60919,7 +60969,8 @@
       "support_default_value": 0,
       "field_category_text": "Functions",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Function"

From dccf9c0141b4c6d5064f5547e5b6a20cfb333f74 Mon Sep 17 00:00:00 2001
From: anlyyao <anly_yaw@163.com>
Date: Thu, 23 Apr 2026 11:46:01 +0800
Subject: [PATCH 2/3] feat(Form): add shouldUpdate and initialData props

---
 db/TDesign.db                                 | Bin 1134592 -> 1134592 bytes
 .../src/form/defaultProps.ts                  |   1 +
 .../src/form/form.en-US.md                    |   5 ++++-
 .../tdesign-mobile-react/src/form/form.md     |   5 ++++-
 .../tdesign-mobile-react/src/form/type.ts     |  17 ++++++++++++++++-
 packages/scripts/api.json                     |  18 ++++++++++++------
 6 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/db/TDesign.db b/db/TDesign.db
index 9d8d75c3a4b3edba3a79d5aa74c7e7ba17a4d7e5..26bb8d93c9ea1ff11bcb82602b2ac418923f98b9 100644
GIT binary patch
delta 105
zcmZoz;M%ajb%Hb_??f4AM&8DR)&$0_2~0C;7=_w@)-VAvGZ3=?G3)l9HEivzK=DQ<
q_U(;K975Va_7q(XAm#*OE+FOxVjdvo1!6uR<_BVd?Nf9GbCdwnpCp6;

delta 105
zcmZoz;M%ajb%Hb_*F+g-My|$$)&$0_2~0C;7@69C)_^cG5VHU=>-L{DZ0)T;@kS>0
p?Tt(vLfSy~6kQG=<^*CcAm#>Q9w6ogVm=_|2V#NkQ*;G$lmNzFBu)ST

diff --git a/packages/products/tdesign-mobile-react/src/form/defaultProps.ts b/packages/products/tdesign-mobile-react/src/form/defaultProps.ts
index 4cf5189ad..91bf7a0fe 100644
--- a/packages/products/tdesign-mobile-react/src/form/defaultProps.ts
+++ b/packages/products/tdesign-mobile-react/src/form/defaultProps.ts
@@ -23,5 +23,6 @@ export const formItemDefaultProps: TdFormItemProps = {
   arrow: false,
   label: '',
   requiredMark: undefined,
+  shouldUpdate: false,
   showErrorMessage: undefined,
 };
diff --git a/packages/products/tdesign-mobile-react/src/form/form.en-US.md b/packages/products/tdesign-mobile-react/src/form/form.en-US.md
index 33d8aa845..59746363e 100644
--- a/packages/products/tdesign-mobile-react/src/form/form.en-US.md
+++ b/packages/products/tdesign-mobile-react/src/form/form.en-US.md
@@ -13,6 +13,7 @@ contentAlign | String | left | options: left/right | N
 disabled | Boolean | undefined | \- | N
 errorMessage | Object | - | Typescript: `FormErrorMessage` | N
 id | String | undefined |  native id attribute of the form，which supports being used in conjunction with non-form buttons through the form attribute to trigger form events | N
+initialData | Object | - | \- | N
 labelAlign | String | right | options: left/right/top | N
 labelWidth | String / Number | '81px' | \- | N
 preventSubmitDefault | Boolean | true | \- | N
@@ -40,7 +41,7 @@ currentElement | \- | `HTMLFormElement` | \-
 getCurrentElement | \- | `HTMLFormElement` | \-
 getFieldValue | `(field: NamePath) ` | `unknown` | required
 getFieldsValue | `(nameList: string[] \| boolean)` | `getFieldsValue<FormData>` | required。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface getFieldsValue<T>{ (nameList: true): T; (nameList: any[]): Record<keyof T, unknown>;}`<br/>
-getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| voi` | required
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| void` | required
 reset | `(params?: FormResetParams<FormData>)` | \- | required。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
 setFields | `(fields: FieldData[])` | \- | required。Typescript: `(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)
 setFieldsValue | `(field: Data)` | \- | required
@@ -60,12 +61,14 @@ arrow | Boolean | false | \- | N
 contentAlign | String | - | options: left/right | N
 for | String | - | \- | N
 help | TNode | - | Typescript: `string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
+initialData | String / Number / Object / Array | - | Typescript: `InitialData` `type InitialData = any`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts) | N
 label | TNode | '' | Typescript: `string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
 labelAlign | String | - | options: left/right/top | N
 labelWidth | String / Number | - | \- | N
 name | String / Number / Array | - | Typescript: `NamePath` `type NamePath = string \| number \| Array<string \| number>`。[see more ts definition](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts) | N
 requiredMark | Boolean | undefined | \- | N
 rules | Array | - | Typescript: `Array<FormRule>` | N
+shouldUpdate | Boolean / Function | false | Typescript: `boolean \| ((prevValue, curValue) => boolean)` | N
 showErrorMessage | Boolean | undefined | \- | N
 
 ### FormRule
diff --git a/packages/products/tdesign-mobile-react/src/form/form.md b/packages/products/tdesign-mobile-react/src/form/form.md
index a958b34c5..390dc6b2f 100644
--- a/packages/products/tdesign-mobile-react/src/form/form.md
+++ b/packages/products/tdesign-mobile-react/src/form/form.md
@@ -13,6 +13,7 @@ contentAlign | String | left | 表单内容对齐方式：左对齐、右对齐
 disabled | Boolean | undefined | 是否禁用整个表单 | N
 errorMessage | Object | - | 表单错误信息配置，示例：`{ idcard: '请输入正确的身份证号码', max: '字符长度不能超过 ${max}' }`。TS 类型：`FormErrorMessage` | N
 id | String | undefined | 表单原生的id属性，支持用于配合非表单内的按钮通过form属性来触发表单事件 | N
+initialData | Object | - | 表单初始数据，重置时所需初始数据，优先级小于 FormItem 设置的 initialData | N
 labelAlign | String | right | 表单字段标签对齐方式：左对齐、右对齐、顶部对齐。可选项：left/right/top | N
 labelWidth | String / Number | '81px' | 可以整体设置label标签宽度，默认为81px | N
 preventSubmitDefault | Boolean | true | 是否阻止表单提交默认事件（表单提交默认事件会刷新页面），设置为 `true` 可以避免刷新 | N
@@ -40,7 +41,7 @@ currentElement | \- | `HTMLFormElement` | 获取 form dom 元素
 getCurrentElement | \- | `HTMLFormElement` | 获取 form dom 元素
 getFieldValue | `(field: NamePath) ` | `unknown` | 必需。获取单个字段值
 getFieldsValue | `(nameList: string[] \| boolean)` | `getFieldsValue<FormData>` | 必需。获取一组字段名对应的值，当调用 getFieldsValue(true) 时返回所有表单数据。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface getFieldsValue<T>{ (nameList: true): T; (nameList: any[]): Record<keyof T, unknown>;}`<br/>
-getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| voi` | 必需。获取校验结果，当调用 getValidateMessage() 时返回所有校验结果
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| void` | 必需。获取校验结果，当调用 getValidateMessage() 时返回所有校验结果
 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-mobile-react/tree/develop/src/form/type.ts)。<br/>`interface FormResetParams<FormData> { type?: 'initial' \| 'empty'; fields?: Array<keyof FormData> }`<br/>
 setFields | `(fields: FieldData[])` | \- | 必需。设置多组字段状态。TS 类型：`(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts)
 setFieldsValue | `(field: Data)` | \- | 必需。设置表单字段值
@@ -60,12 +61,14 @@ arrow | Boolean | false | 是否显示右侧箭头 | N
 contentAlign | String | - | 表单内容对齐方式，优先级高于 Form.contentAlign。可选项：left/right | N
 for | String | - | label 原生属性 | N
 help | TNode | - | 表单项说明内容。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
+initialData | String / Number / Object / Array | - | 表单初始数据，重置时所需初始数据。TS 类型：`InitialData` `type InitialData = any`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts) | N
 label | TNode | '' | 字段标签名称。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-mobile-react/blob/develop/src/common.ts) | N
 labelAlign | String | - | 表单字段标签对齐方式：左对齐、右对齐、顶部对齐。默认使用 Form 的对齐方式，优先级高于 Form.labelAlign。可选项：left/right/top | N
 labelWidth | String / Number | - | 可以整体设置标签宽度，优先级高于 Form.labelWidth | N
 name | String / Number / Array | - | 表单字段名称。TS 类型：`NamePath` `type NamePath = string \| number \| Array<string \| number>`。[详细类型定义](https://github.com/Tencent/tdesign-mobile-react/tree/develop/src/form/type.ts) | N
 requiredMark | Boolean | undefined | 是否显示必填符号（*），优先级高于 Form.requiredMark | N
 rules | Array | - | 表单字段校验规则。TS 类型：`Array<FormRule>` | N
+shouldUpdate | Boolean / Function | false | TS 类型：`boolean \| ((prevValue, curValue) => boolean)` | N
 showErrorMessage | Boolean | undefined | 校验不通过时，是否显示错误提示信息，优先级高于 `Form.showErrorMessage` | N
 
 ### FormRule
diff --git a/packages/products/tdesign-mobile-react/src/form/type.ts b/packages/products/tdesign-mobile-react/src/form/type.ts
index 38bc242f0..9b5bad98f 100644
--- a/packages/products/tdesign-mobile-react/src/form/type.ts
+++ b/packages/products/tdesign-mobile-react/src/form/type.ts
@@ -31,6 +31,10 @@ export interface TdFormProps<FormData extends Data = Data> {
    * 表单原生的id属性，支持用于配合非表单内的按钮通过form属性来触发表单事件
    */
   id?: string;
+  /**
+   * 表单初始数据，重置时所需初始数据，优先级小于 FormItem 设置的 initialData
+   */
+  initialData?: object;
   /**
    * 表单字段标签对齐方式：左对齐、右对齐、顶部对齐
    * @default right
@@ -124,7 +128,7 @@ export interface FormInstanceFunctions<FormData extends Data = Data> {
   /**
    * 获取校验结果，当调用 getValidateMessage() 时返回所有校验结果
    */
-  getValidateMessage: (fields?: Array<keyof FormData>) => Array<FormRule> | voi;
+  getValidateMessage: (fields?: Array<keyof FormData>) => Array<FormRule> | void;
   /**
    * 重置表单，表单里面没有重置按钮`<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'] })`
    */
@@ -174,6 +178,10 @@ export interface TdFormItemProps {
    * 表单项说明内容
    */
   help?: TNode;
+  /**
+   * 表单初始数据，重置时所需初始数据
+   */
+  initialData?: InitialData;
   /**
    * 字段标签名称
    * @default ''
@@ -199,6 +207,11 @@ export interface TdFormItemProps {
    * 表单字段校验规则
    */
   rules?: Array<FormRule>;
+  /**
+   * null
+   * @default false
+   */
+  shouldUpdate?: boolean | ((prevValue, curValue) => boolean);
   /**
    * 校验不通过时，是否显示错误提示信息，优先级高于 `Form.showErrorMessage`
    */
@@ -417,6 +430,8 @@ export type ValidateTriggerType = 'blur' | 'change' | 'submit' | 'all';
 
 export type Data = { [key: string]: any };
 
+export type InitialData = any;
+
 export type NamePath = string | number | Array<string | number>;
 
 export interface IsDateOptions {
diff --git a/packages/scripts/api.json b/packages/scripts/api.json
index e5d487180..47ae5c2d8 100644
--- a/packages/scripts/api.json
+++ b/packages/scripts/api.json
@@ -59756,7 +59756,8 @@
     {
       "id": 2868,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 1,
@@ -59784,7 +59785,8 @@
       "support_default_value": 0,
       "field_category_text": "Props",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Object"
@@ -62241,7 +62243,8 @@
     {
       "id": 1066,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "FormItem",
       "field_category": 1,
@@ -62272,7 +62275,8 @@
       "support_default_value": 0,
       "field_category_text": "Props",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "String",
@@ -62644,7 +62648,8 @@
     {
       "id": 3008,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "FormItem",
       "field_category": 1,
@@ -62673,7 +62678,8 @@
       "support_default_value": 0,
       "field_category_text": "Props",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Boolean",

From 9f7aef85d90fe0d530d3360d19c668208eca1353 Mon Sep 17 00:00:00 2001
From: anlyyao <anly_yaw@163.com>
Date: Thu, 23 Apr 2026 11:57:25 +0800
Subject: [PATCH 3/3] feat(Form): add form prop

---
 db/TDesign.db                                 | Bin 1134592 -> 1134592 bytes
 .../src/form/form.en-US.md                    |   1 +
 .../tdesign-mobile-react/src/form/form.md     |   1 +
 .../tdesign-mobile-react/src/form/type.ts     |   4 ++++
 packages/scripts/api.json                     |   6 ++++--
 5 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/db/TDesign.db b/db/TDesign.db
index e53d0c2cd17271c3372953b4e8b0d3d1c810d407..92945e829869a9f585584552fe1403c7b3e91892 100644
GIT binary patch
delta 88
zcmZoz;M%ajb%Hdb=tLQ3R#67MvaZII))dCp6sFb`=GGLJ))dy(6t=A?>>Otqh1zq^
gvI8*(5OV@C7Z7s;F%J;)0x=&D^KZ{RD=@hU08h{%egFUf

delta 88
zcmZoz;M%ajb%Hdb$V3@uRuKlhHqFMA))dCp6sFb`=GGLJ))dy(6t=A?>>Otqnc8#D
gvI8*(5OV@C7Z7s;F%J;)0x=&D^KZ{RD=@hU05)+U8vp<R

diff --git a/packages/products/tdesign-mobile-react/src/form/form.en-US.md b/packages/products/tdesign-mobile-react/src/form/form.en-US.md
index 59746363e..149690e45 100644
--- a/packages/products/tdesign-mobile-react/src/form/form.en-US.md
+++ b/packages/products/tdesign-mobile-react/src/form/form.en-US.md
@@ -12,6 +12,7 @@ colon | Boolean | false | \- | N
 contentAlign | String | left | options: left/right | N
 disabled | Boolean | undefined | \- | N
 errorMessage | Object | - | Typescript: `FormErrorMessage` | N
+form | Object | - | Typescript: `FormInstanceFunctions` | N
 id | String | undefined |  native id attribute of the form，which supports being used in conjunction with non-form buttons through the form attribute to trigger form events | N
 initialData | Object | - | \- | N
 labelAlign | String | right | options: left/right/top | N
diff --git a/packages/products/tdesign-mobile-react/src/form/form.md b/packages/products/tdesign-mobile-react/src/form/form.md
index 390dc6b2f..c36fda573 100644
--- a/packages/products/tdesign-mobile-react/src/form/form.md
+++ b/packages/products/tdesign-mobile-react/src/form/form.md
@@ -12,6 +12,7 @@ colon | Boolean | false | 是否在表单标签字段右侧显示冒号 | N
 contentAlign | String | left | 表单内容对齐方式：左对齐、右对齐。可选项：left/right | N
 disabled | Boolean | undefined | 是否禁用整个表单 | N
 errorMessage | Object | - | 表单错误信息配置，示例：`{ idcard: '请输入正确的身份证号码', max: '字符长度不能超过 ${max}' }`。TS 类型：`FormErrorMessage` | N
+form | Object | - | 经 `Form.useForm()` 创建的 form 控制实例。TS 类型：`FormInstanceFunctions` | N
 id | String | undefined | 表单原生的id属性，支持用于配合非表单内的按钮通过form属性来触发表单事件 | N
 initialData | Object | - | 表单初始数据，重置时所需初始数据，优先级小于 FormItem 设置的 initialData | N
 labelAlign | String | right | 表单字段标签对齐方式：左对齐、右对齐、顶部对齐。可选项：left/right/top | N
diff --git a/packages/products/tdesign-mobile-react/src/form/type.ts b/packages/products/tdesign-mobile-react/src/form/type.ts
index 9b5bad98f..1644b80d7 100644
--- a/packages/products/tdesign-mobile-react/src/form/type.ts
+++ b/packages/products/tdesign-mobile-react/src/form/type.ts
@@ -27,6 +27,10 @@ export interface TdFormProps<FormData extends Data = Data> {
    * 表单错误信息配置，示例：`{ idcard: '请输入正确的身份证号码', max: '字符长度不能超过 ${max}' }`
    */
   errorMessage?: FormErrorMessage;
+  /**
+   * 经 `Form.useForm()` 创建的 form 控制实例
+   */
+  form?: FormInstanceFunctions;
   /**
    * 表单原生的id属性，支持用于配合非表单内的按钮通过form属性来触发表单事件
    */
diff --git a/packages/scripts/api.json b/packages/scripts/api.json
index 4330bacb7..a657d476e 100644
--- a/packages/scripts/api.json
+++ b/packages/scripts/api.json
@@ -59694,7 +59694,8 @@
     {
       "id": 2940,
       "platform_framework": [
-        "2"
+        "2",
+        "16"
       ],
       "component": "Form",
       "field_category": 1,
@@ -59722,7 +59723,8 @@
       "support_default_value": 0,
       "field_category_text": "Props",
       "platform_framework_text": [
-        "React(PC)"
+        "React(PC)",
+        "React(Mobile)"
       ],
       "field_type_text": [
         "Object"