aha-components 1.5.8 → 1.6.1

package/dist/components/Form/index.d.ts

@@ -30,6 +30,22 @@ export interface FormProps {
     /** 子元素 */
     children?: React.ReactNode;
 }
+/** scrollToField 的选项，与 Element.scrollIntoView 一致 */
+export type ScrollToFieldOptions = ScrollIntoViewOptions;
+/** 校验失败时抛出的错误，携带 values 和 errorFields，便于 catch 后使用 */
+export declare class FormValidationError extends Error {
+    /** 当前表单值 */
+    values: Record<string, any>;
+    /** 校验失败的字段列表 */
+    errorFields: Array<{
+        name: string;
+        errors: string[];
+    }>;
+    constructor(message: string, values: Record<string, any>, errorFields: Array<{
+        name: string;
+        errors: string[];
+    }>);
+}
 export interface FormInstance {
     /** 获取字段值 */
     getFieldValue: (name: string) => any;
@@ -39,6 +55,12 @@ export interface FormInstance {
     setFieldValue: (name: string, value: any) => void;
     /** 设置所有字段值 */
     setFieldsValue: (values: Record<string, any>) => void;
+    /** 批量设置字段（值 + 错误），类似 antd 的 setFields */
+    setFields: (fields: Array<{
+        name: string;
+        value?: any;
+        errors?: string[];
+    }>) => void;
     /** 获取字段错误 */
     getFieldError: (name: string) => string | undefined;
     /** 校验字段 */
@@ -47,11 +69,17 @@ export interface FormInstance {
     validateFields: (nameList?: string[]) => Promise<any>;
     /** 重置字段 */
     resetFields: (nameList?: string[]) => void;
-    /** 提交表单 */
+    /** 提交表单：校验通过时 resolve 表单值，校验失败时 reject 为 FormValidationError（需 await 或 .catch() 才能捕获） */
     submit: () => Promise<any>;
+    /** 滚动到指定字段（如第一个报错项） */
+    scrollToField: (name: string, options?: ScrollToFieldOptions) => void;
 }
 declare const Form: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<FormInstance>>;
+/** 获取表单实例的 hook，用法与 antd Form.useForm() 一致，返回的 ref 传给 <Form ref={formRef} /> 后即可使用 formRef.current?.setFieldValue 等方法 */
+declare function useForm(): [React.RefObject<FormInstance | null>];
 declare const FormWithItem: typeof Form & {
     Item: typeof FormItem;
+    useForm: typeof useForm;
 };
 export default FormWithItem;
+export { useForm };

package/dist/index.d.ts

@@ -725,6 +725,8 @@ interface FormProps {
     /** 子元素 */
     children?: React.ReactNode;
 }
+/** scrollToField 的选项，与 Element.scrollIntoView 一致 */
+type ScrollToFieldOptions = ScrollIntoViewOptions;
 interface FormInstance {
     /** 获取字段值 */
     getFieldValue: (name: string) => any;
@@ -734,6 +736,12 @@ interface FormInstance {
     setFieldValue: (name: string, value: any) => void;
     /** 设置所有字段值 */
     setFieldsValue: (values: Record<string, any>) => void;
+    /** 批量设置字段（值 + 错误），类似 antd 的 setFields */
+    setFields: (fields: Array<{
+        name: string;
+        value?: any;
+        errors?: string[];
+    }>) => void;
     /** 获取字段错误 */
     getFieldError: (name: string) => string | undefined;
     /** 校验字段 */
@@ -742,12 +750,17 @@ interface FormInstance {
     validateFields: (nameList?: string[]) => Promise<any>;
     /** 重置字段 */
     resetFields: (nameList?: string[]) => void;
-    /** 提交表单 */
+    /** 提交表单：校验通过时 resolve 表单值，校验失败时 reject 为 FormValidationError（需 await 或 .catch() 才能捕获） */
     submit: () => Promise<any>;
+    /** 滚动到指定字段（如第一个报错项） */
+    scrollToField: (name: string, options?: ScrollToFieldOptions) => void;
 }
 declare const Form: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<FormInstance>>;
+/** 获取表单实例的 hook，用法与 antd Form.useForm() 一致，返回的 ref 传给 <Form ref={formRef} /> 后即可使用 formRef.current?.setFieldValue 等方法 */
+declare function useForm(): [React.RefObject<FormInstance | null>];
 declare const FormWithItem: typeof Form & {
     Item: typeof FormItem;
+    useForm: typeof useForm;
 };
 
 interface MenuItemType {