feat: support custom label name for validation messages (#365)

Author: ziqisia

packages/arcodesign/components/form/__test__/index.spec.js

@@ -264,3 +264,131 @@ describe('Form input', () => {
         });
     });
 });
+
+
+describe('Form validate label', () => {
+    // Scenario 1: Default Scenario (labelName only)
+    it('should use labelName for display and validation when label is missing', async () => {
+        const formRef = React.createRef();
+        render(
+            <Form ref={formRef}>
+                <Form.Item labelName="Label Name Only" field="label_name_only" required>
+                    <Input />
+                </Form.Item>
+            </Form>,
+        );
+        // Check display
+        expect(screen.getByText('Label Name Only')).toBeInTheDocument();
+        
+        // Check validation
+        act(() => {
+            formRef.current.form.validateFields().catch(() => {});
+        });
+        await waitFor(() => {
+            expect(screen.getByText('Label Name Only 为必填项')).toBeInTheDocument();
+        });
+    });
+
+    // Scenario 2: ReactNode Customization (label + labelName)
+    it('should use label for display and labelName for validation when both provided (label is Node)', async () => {
+        const formRef = React.createRef();
+        render(
+            <Form ref={formRef}>
+                <Form.Item 
+                    label={<span>Complex Label</span>} 
+                    labelName="Label Name Validation" 
+                    field="complex_custom" 
+                    required
+                >
+                    <Input />
+                </Form.Item>
+            </Form>,
+        );
+        // Check display (should render ReactNode)
+        expect(screen.getByText('Complex Label')).toBeInTheDocument();
+        
+        // Check validation (should use labelName)
+        act(() => {
+            formRef.current.form.validateFields().catch(() => {});
+        });
+        await waitFor(() => {
+            expect(screen.getByText('Label Name Validation 为必填项')).toBeInTheDocument();
+        });
+    });
+
+    // Scenario 3a: String Label Only
+    it('should use string label for display and validation', async () => {
+        const formRef = React.createRef();
+        render(
+            <Form ref={formRef}>
+                <Form.Item label="String Label" field="string_label" required>
+                    <Input />
+                </Form.Item>
+            </Form>,
+        );
+        // Check display
+        expect(screen.getByText('String Label')).toBeInTheDocument();
+        
+        // Check validation
+        act(() => {
+            formRef.current.form.validateFields().catch(() => {});
+        });
+        await waitFor(() => {
+            expect(screen.getByText('String Label 为必填项')).toBeInTheDocument();
+        });
+    });
+
+    // Scenario 3b: ReactNode Label Only
+    it('should use ReactNode for display and field for validation when labelName missing', async () => {
+        const formRef = React.createRef();
+        render(
+            <Form ref={formRef}>
+                <Form.Item label={<span>Node Label</span>} field="node_field" required>
+                    <Input />
+                </Form.Item>
+            </Form>,
+        );
+        // Check display
+        expect(screen.getByText('Node Label')).toBeInTheDocument();
+        
+        // Check validation (fallback to field)
+        act(() => {
+            formRef.current.form.validateFields().catch(() => {});
+        });
+        await waitFor(() => {
+            expect(screen.getByText('node_field 为必填项')).toBeInTheDocument();
+        });
+    });
+
+    // Edge Case: String Label + Label Name
+    // Rule says: "Default scenario... prioritize labelName... used for Display"
+    // BUT "ReactNode Customization... Must provide both... label used for rendering"
+    // Since we treat provided label as "Customization/Override", label (string) should override display, but labelName should override validation?
+    // Let's verify behavior matches implementation:
+    // Display: label ?? labelName -> label
+    // Validation: labelName || label -> labelName
+    it('should use label for display and labelName for validation if both strings are provided', async () => {
+        const formRef = React.createRef();
+        render(
+            <Form ref={formRef}>
+                <Form.Item 
+                    label="Display String" 
+                    labelName="Validation String" 
+                    field="mixed_string" 
+                    required
+                >
+                    <Input />
+                </Form.Item>
+            </Form>,
+        );
+        // Check display
+        expect(screen.getByText('Display String')).toBeInTheDocument();
+        // Check validation
+        act(() => {
+            formRef.current.form.validateFields().catch(() => {});
+        });
+        await waitFor(() => {
+            expect(screen.getByText('Validation String 为必填项')).toBeInTheDocument();
+        });
+    });
+});

packages/arcodesign/components/form/form-item.tsx

@@ -116,7 +116,7 @@ class FormItemInner extends PureComponent<IFormItemInnerProps, IFormItemInnerSta
     validateField = (validateTrigger?: string): Promise<IFieldError> => {
         const { validateMessages } = this.context;
         const { getFieldValue } = this.context.form;
-        const { field, rules, onValidateStatusChange } = this.props;
+        const { field, rules, onValidateStatusChange, labelName } = this.props;
         const value = getFieldValue(field);
         // rules: if validateTrigger is not defined, all rules will be validated
         // if validateTrigger is defined, only rules  with validateTrigger  or  without rule.validateTrigger  will be validated
@@ -131,13 +131,17 @@ class FormItemInner extends PureComponent<IFormItemInnerProps, IFormItemInnerSta
 
         if (curRules?.length && field) {
             const fieldDom = this.props.getFormItemRef();
-            const fieldValidator = new Validator({ [field]: curRules }, { validateMessages });
+            const validateFieldName = labelName || field;
+            const fieldValidator = new Validator(
+                { [validateFieldName]: curRules },
+                { validateMessages },
+            );
             return new ES6Promise<IFieldError>(resolve => {
                 fieldValidator.validate(
-                    { [field]: value },
+                    { [validateFieldName]: value },
                     (errorsMap: Record<string, ValidatorError[]>) => {
                         const { errors, warnings, errorTypes } = getErrorAndWarnings(
-                            errorsMap?.[field] || [],
+                            errorsMap?.[validateFieldName] || [],
                         );
                         this._errors = errors;
                         onValidateStatusChange({
@@ -284,6 +288,7 @@ export default forwardRef((props: FormItemProps, ref: Ref<FormItemRef>) => {
         requiredIcon,
         rules,
         className = '',
+        labelName,
         ...rest
     } = props;
     const { prefixCls } = useContext(GlobalContext);
@@ -292,6 +297,10 @@ export default forwardRef((props: FormItemProps, ref: Ref<FormItemRef>) => {
     const [errorTypes, setErrorTypes] = useState<string | null>(null);
     const [warnings, setWarnings] = useState<ReactNode[]>([]);
     const formItemRef = useRef<HTMLDivElement | null>(null);
+    // Prioritize user provided label (if exists and valid string).
+    // Only use labelName as substitute when label is invalid (not a string) or not provided.
+    const labelStr = labelName || (typeof label === 'string' ? label : undefined);
+    const renderedLabel = label !== undefined ? label : labelName;
 
     const onValidateStatusChange = (validateResult: {
         errors: ReactNode[];
@@ -340,7 +349,7 @@ export default forwardRef((props: FormItemProps, ref: Ref<FormItemRef>) => {
                           </span>
                       )
                     : null}
-                {label}
+                {renderedLabel}
             </div>
             <div className={cls(`${prefixCls}-form-item-control-wrapper`)}>
                 <div className={cls(`${prefixCls}-form-item-control`)}>
@@ -349,6 +358,7 @@ export default forwardRef((props: FormItemProps, ref: Ref<FormItemRef>) => {
                         rules={fieldRules}
                         disabled={fieldDisabled}
                         field={field}
+                        labelName={labelStr}
                         onValidateStatusChange={onValidateStatusChange}
                         getFormItemRef={getFormItemRef}
                     />

packages/arcodesign/components/form/type.ts

@@ -256,7 +256,12 @@ export interface FormItemProps {
      * 表单项名
      * @en The form item name
      */
-    label: ReactNode;
+    label?: ReactNode;
+    /**
+     * 校验提示中的字段名（当 label 为复杂节点时推荐设置）
+     * @en The field name in the validation message (recommended when label is a complex node)
+     */
+    labelName?: string;
     /**
      * 表单项Stylesheet
      * @en The form item stylesheet
@@ -345,6 +350,11 @@ export interface IFormItemInnerProps {
      * @en Form item field
      */
     field: string;
+    /**
+     * 校验提示中的字段名
+     * @en The field name in the validation message
+     */
+    labelName?: string;
     /**
      * 表单项子节点
      * @en Form item children