feat(form): support requiredMarkPosition (#3586)

Wesley-0808 · web-flow · commit e94cb3399aaf · 2025-06-13T10:18:01.000+08:00
* feat(form): docs &amp; type &amp; props

* feat(config): docs &amp; type

* feat(form): support requiredMarkPosition

* feat(form): support requiredMarkPosition
diff --git a/packages/components/config-provider/config-provider.en-US.md b/packages/components/config-provider/config-provider.en-US.md
@@ -172,6 +172,7 @@ name | type | default | description | required
 colonText | String | - | colon on the right of label ":" | N
 errorMessage | Object | - | Typescript：`FormErrorMessage`，[Form API Documents](./form?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/config-provider/type.ts) | N
 requiredMark | Boolean | true | \- | N
+requiredMarkPosition | String | left | Display position of required symbols。options: left/right | N
 
 ### GuideConfig
 
diff --git a/packages/components/config-provider/config-provider.md b/packages/components/config-provider/config-provider.md
@@ -202,6 +202,7 @@ titleText | Object | - | 空状态组件各类型的标题文本配置。TS 类
 colonText | String | - | 字段旁边的冒号，中文为“：” | N
 errorMessage | Object | - | 表单错误信息配置，示例：`{ idcard: '请输入正确的身份证号码', max: '字符长度不能超过 ${max}' }`。TS 类型：`FormErrorMessage`，[Form API Documents](./form?tab=api)。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/packages/components/config-provider/type.ts) | N
 requiredMark | Boolean | true | 是否显示必填符号（*），默认显示 | N
+requiredMarkPosition | String | left | 表单必填符号（*）显示位置。可选项：left/right | N
 
 ### GuideConfig
 
diff --git a/packages/components/config-provider/type.ts b/packages/components/config-provider/type.ts
@@ -509,6 +509,11 @@ export interface FormConfig {
    * @default true
    */
   requiredMark?: boolean;
+  /**
+   * 表单必填符号（*）显示位置
+   * @default left
+   */
+  requiredMarkPosition?: 'left' | 'right';
 }
 
 export interface GuideConfig {
diff --git a/packages/components/form/Form.tsx b/packages/components/form/Form.tsx
@@ -32,6 +32,7 @@ const Form = forwardRefWithStatics(
       colon,
       initialData,
       requiredMark = globalFormConfig.requiredMark,
+      requiredMarkPosition = globalFormConfig.requiredMarkPosition,
       scrollToFirstError,
       showErrorMessage,
       resetType,
@@ -98,6 +99,7 @@ const Form = forwardRefWithStatics(
           colon,
           initialData,
           requiredMark,
+          requiredMarkPosition,
           errorMessage,
           showErrorMessage,
           scrollToFirstError,
diff --git a/packages/components/form/FormContext.tsx b/packages/components/form/FormContext.tsx
@@ -12,6 +12,7 @@ const FormContext = React.createContext<{
   colon: TdFormProps['colon'];
   initialData: TdFormProps['initialData'];
   requiredMark: TdFormProps['requiredMark'];
+  requiredMarkPosition: TdFormProps['requiredMarkPosition'];
   scrollToFirstError: TdFormProps['scrollToFirstError'];
   showErrorMessage: TdFormProps['showErrorMessage'];
   resetType: TdFormProps['resetType'];
@@ -29,6 +30,7 @@ const FormContext = React.createContext<{
   colon: false,
   initialData: {},
   requiredMark: undefined,
+  requiredMarkPosition: undefined,
   scrollToFirstError: undefined,
   showErrorMessage: undefined,
   resetType: 'empty',
diff --git a/packages/components/form/FormItem.tsx b/packages/components/form/FormItem.tsx
@@ -60,6 +60,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     colon,
     layout,
     requiredMark: requiredMarkFromContext,
+    requiredMarkPosition,
     labelAlign: labelAlignFromContext,
     labelWidth: labelWidthFromContext,
     showErrorMessage: showErrorMessageFromContext,
@@ -153,6 +154,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
       labelWidth,
       labelAlign,
       requiredMark,
+      requiredMarkPosition,
       showErrorMessage,
       innerRules,
     });
diff --git a/packages/components/form/_usage/props.json b/packages/components/form/_usage/props.json
@@ -57,6 +57,21 @@
     "defaultValue": false,
     "options": []
   },
+  {
+    "name": "requiredMarkPosition",
+    "type": "enum",
+    "defaultValue": "left",
+    "options": [
+      {
+        "label": "left",
+        "value": "left"
+      },
+      {
+        "label": "right",
+        "value": "right"
+      }
+    ]
+  },
   {
     "name": "resetType",
     "type": "enum",
diff --git a/packages/components/form/form.en-US.md b/packages/components/form/form.en-US.md
@@ -20,6 +20,7 @@ labelWidth | String / Number | '100px' | \- | N
 layout | String | vertical | options: vertical/inline | N
 preventSubmitDefault | Boolean | true | \- | N
 requiredMark | Boolean | true | \- | N
+requiredMarkPosition | String | left | Display position of required symbols。options: left/right | N
 resetType | 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-react/blob/develop/packages/components/form/type.ts) | N
 scrollToFirstError | String | - | options: ''/smooth/auto | N
diff --git a/packages/components/form/form.md b/packages/components/form/form.md
@@ -102,6 +102,7 @@ labelWidth | String / Number | '100px' | 可以整体设置label标签宽度，
 layout | String | vertical | 表单布局，有两种方式：纵向布局 和 行内布局。可选项：vertical/inline | N
 preventSubmitDefault | Boolean | true | 是否阻止表单提交默认事件（表单提交默认事件会刷新页面），设置为 `true` 可以避免刷新 | N
 requiredMark | Boolean | true | 是否显示必填符号（*），默认显示 | N
+requiredMarkPosition | String | left | 表单必填符号（*）显示位置。可选项：left/right | N
 resetType | 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-react/blob/develop/packages/components/form/type.ts) | N
 scrollToFirstError | String | - | 表单校验不通过时，是否自动滚动到第一个校验不通过的字段，平滑滚动或是瞬间直达。值为空则表示不滚动。可选项：''/smooth/auto | N
diff --git a/packages/components/form/hooks/useFormItemStyle.tsx b/packages/components/form/hooks/useFormItemStyle.tsx
@@ -22,6 +22,7 @@ export default function useFormItemStyle(props) {
     labelWidth,
     labelAlign,
     requiredMark,
+    requiredMarkPosition,
     showErrorMessage,
     innerRules,
   } = props;
@@ -71,6 +72,7 @@ export default function useFormItemStyle(props) {
 
   const formItemLabelClass = classNames(`${classPrefix}-form__label`, {
     [`${classPrefix}-form__label--required`]: needRequiredMark,
+    [`${classPrefix}-form__label--required-right`]: needRequiredMark && requiredMarkPosition === 'right',
     [`${classPrefix}-form__label--top`]: labelAlign === 'top' || !labelWidth,
     [`${classPrefix}-form__label--left`]: labelAlign === 'left' && labelWidth,
     [`${classPrefix}-form__label--right`]: labelAlign === 'right' && labelWidth,
diff --git a/packages/components/form/type.ts b/packages/components/form/type.ts
@@ -62,6 +62,10 @@ export interface TdFormProps<FormData extends Data = Data> {
    * 是否显示必填符号（*），默认显示
    */
   requiredMark?: boolean;
+  /**
+   * 表单必填符号（*）显示位置
+   */
+  requiredMarkPosition?: 'left' | 'right';
   /**
    * 重置表单的方式，值为 empty 表示重置表单为空，值为 initial 表示重置表单数据为初始值
    * @default empty
