chore(Form): enhance FormInstanceFunctions

[anlyyao]

🤔 这个 PR 的性质是？

• 日常 bug 修复
• 新特性提交
• 文档改进
• 演示代码改进
• 组件样式/交互改进
• CI/CD 改进
• 重构
• 代码风格优化
• 测试用例
• 分支合并
• 其他

🔗 相关 Issue

相关 PRs

TDesignOteam/tdesign-api#852

💡 需求背景和解决方案

📝 更新日志

• feat(Form): 新增 readonly、form、initialData 属性

• feat(Form): name 属性新增 Number、 Array 类型

• feat(Form): 为 FormInstanceFunctions 组件实例新增 setFields、setFieldsValue、getFieldValue、getFieldsValue 等方法

• feat(FormItem): 新增 initialData 和 shouldUpdate 属性

• fix(Form): 修复 onValuesChange 事件无效

• fix(Form): 修复 preventSubmitDefault、showErrorMessage 等属性默认值无效

• fix(Form): 修复 FormInstanceFunctions 的 validate() 校验结果错误

• 本条 PR 不需要纳入 Changelog

☑️ 请求合并前的自查清单

⚠️ 请自检并全部勾选全部选项。⚠️

• 文档已补充或无须补充
• 代码演示已提供或无须提供
• TypeScript 定义已补充或无须补充
• Changelog 已提供或无须提供

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/tdesign-mobile-react@903

commit: a0c3177

[github-actions]

[anlyyao]

测试示例

import React, { useEffect, useMemo, useRef, useState } from 'react';
import { Button, Form, Input, Radio, RadioGroup, Rate, Stepper, Textarea, Cell, Switch } from 'tdesign-mobile-react';
import { BrowseOffIcon } from 'tdesign-icons-react';

const RATE_GAP = 8;
export default function HorizontalForm({ disabled }) {
  const formRef = useRef(null);
  const isInit = useRef(false);
  const [readonly, setReadonly] = useState(false);

  const rules = useMemo(
    () => ({
      name: [{ validator: (val: any) => val?.length === 8, message: '只能输入8个字符英文' }],
      password: [{ validator: (val: any) => val?.length > 6, message: '长度大于6个字符' }],
      gender: [{ validator: (val: any) => val !== '', message: '不能为空' }],
      birth: [{ validator: (val: any) => val !== '', message: '不能为空' }],
      place: [{ validator: (val: any) => val !== '', message: '不能为空' }],
      description: [{ validator: (val: any) => val > 3, message: '分数过低会影响整体评价' }],
      resume: [{ validator: (val: any) => val !== '', message: '不能为空' }],
      'profile.nickname': [{ required: true, message: '昵称不能为空' }],
      'profile.age': [{ validator: (val: any) => val > 0, message: '年龄必须大于0' }],
    }),
    [],
  );

  useEffect(() => {
    if (isInit.current) {
      return;
    }
    formRef.current?.setValidateMessage(rules);
    isInit.current = true;
  }, [rules]);

  const onReset = () => {
    console.log('===onReset');
  };
  const onSubmit = (e: any) => {
    console.log('===onSubmit', e);
  };

  // 测试新增的方法
  const testGetFieldValue = () => {
    const value = formRef.current?.getFieldValue?.('name');
    console.log(`getFieldValue('name'):`, value);
  };

  const testGetFieldsValue = () => {
    const values = formRef.current?.getFieldsValue?.(true);
    console.log(`getFieldsValue(true):`, values);
  };

  const testSetFieldsValue = () => {
    formRef.current?.setFieldsValue?.({ name: 'testName', age: 25 });
    console.log('setFieldsValue({ name: "testName", age: 25 }) 已执行');
  };

  const testGetValidateMessage = () => {
    const msg = formRef.current?.getValidateMessage?.();
    console.log(`getValidateMessage():`, msg);
  };

  const testSetFields = () => {
    formRef.current?.setFields?.([
      { name: 'name', value: 'setFieldsTest', validateMessage: { type: 'error', message: '测试错误信息' } },
    ]);
    console.log('setFields([{ name: "name", value: "setFieldsTest", ... }]) 已执行');
  };

  const testCurrentElement = () => {
    const el = formRef.current?.currentElement;
    console.log(`currentElement:`, el ? 'HTMLFormElement' : 'null');
  };

  const testGetCurrentElement = () => {
    const el = formRef.current?.getCurrentElement?.();
    console.log(`getCurrentElement():`, el ? 'HTMLFormElement' : 'null');
  };

  // 测试嵌套数据 setFieldsValue
  const testSetNestedFieldsValue = () => {
    formRef.current?.setFieldsValue?.({
      name: 'nestedName',
      age: 30,
      profile: {
        nickname: '小明',
        age: 25,
        enabled: true,
      },
    });
    console.log('setFieldsValue 嵌套数据已执行');
  };

  const toggleReadonly = () => {
    setReadonly(!readonly);
    console.log(`readonly 设置为:`, !readonly);
  };

  return (
    <>
      <Form
        ref={formRef}
        showErrorMessage
        resetType="initial"
        labelAlign="left"
        scrollToFirstError="auto"
        disabled={disabled}
        readonly={readonly}
        rules={rules}
        onReset={onReset}
        onSubmit={onSubmit}
        onValuesChange={(changedValue, allFields) => {
          console.log('===onValuesChange', changedValue, allFields);
        }}
        labelWidth="81px"
      >
        <Form.FormItem label="用户名" name="name" help="请输入用户名">
          <Input borderless placeholder="请输入内容" />
        </Form.FormItem>
        <Form.FormItem label="密码" name="password" help="">
          <Input borderless type="password" placeholder="请输入内容" suffixIcon={<BrowseOffIcon />} />
        </Form.FormItem>
        <Form.FormItem label="性别" name="gender">
          <RadioGroup className="box" borderless>
            <Radio block={false} name="radio" value="man" label="男" />
            <Radio block={false} name="radio" value="woman" label="女" />
            <Radio block={false} name="radio" value="secret" label="保密" />
          </RadioGroup>
        </Form.FormItem>
        <Form.FormItem label="年限" name="age" contentAlign="left">
          <Stepper theme="filled" />
        </Form.FormItem>
        <Form.FormItem label="自我评价" name="description" contentAlign="left">
          <Rate allowHalf showText={false} gap={RATE_GAP} />
        </Form.FormItem>
        <Form.FormItem label="个人简介" name="resume">
          <Textarea className="textarea" indicator maxlength={50} placeholder="请输入个人简介" />
        </Form.FormItem>

        {/* 嵌套数据类型示例 */}
        <div style={{ padding: '16px 0', borderTop: '1px solid #eee', marginTop: '8px' }}>
          <div style={{ fontSize: '14px', color: '#666', marginBottom: '12px' }}>嵌套数据 (name 为 Array)</div>
          <Form.FormItem label="昵称" name={['profile', 'nickname']}>
            <Input borderless placeholder="请输入昵称" />
          </Form.FormItem>
          <Form.FormItem label="年龄" name={['profile', 'age']} contentAlign="left">
            <Stepper theme="filled" min={0} />
          </Form.FormItem>
          <Form.FormItem label="启用" name={['profile', 'enabled']}>
            <Switch />
          </Form.FormItem>
        </div>

        <div className="button-group">
          <Button theme="primary" type="submit" size="large">
            提交
          </Button>
          <Button theme="default" variant="base" type="reset" size="large">
            重置
          </Button>
        </div>
      </Form>

      <Cell title="测试新增 API" description="点击下方按钮测试，结果请查看控制台" />
      <div className="test-buttons" style={{ padding: '16px', display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
        <Button size="small" onClick={testGetFieldValue}>
          getFieldValue
        </Button>
        <Button size="small" onClick={testGetFieldsValue}>
          getFieldsValue
        </Button>
        <Button size="small" onClick={testSetFieldsValue}>
          setFieldsValue
        </Button>
        <Button size="small" onClick={testGetValidateMessage}>
          getValidateMessage
        </Button>
        <Button size="small" onClick={testSetFields}>
          setFields
        </Button>
        <Button size="small" onClick={testCurrentElement}>
          currentElement
        </Button>
        <Button size="small" onClick={testGetCurrentElement}>
          getCurrentElement
        </Button>
        <Button size="small" onClick={testSetNestedFieldsValue}>
          setNestedValue
        </Button>
        <Button size="small" theme="primary" variant="outline" onClick={toggleReadonly}>
          {readonly ? '取消只读' : '设置只读'}
        </Button>
      </div>
    </>
  );
}