@douyinfe/semi-ui/lib/cjs/form/interface.d.ts

A modern, comprehensive, flexible design system and UI library. Connect DesignOps & DevOps. Quickly build beautiful React apps. Maintained by Douyin-fe team.

import * as React from 'react';
import type { RuleItem } from 'async-validator';
import type { Options as ScrollIntoViewOptions } from 'scroll-into-view-if-needed';
import type { BaseFormApi as FormApi, FormState, WithFieldOption, AllErrors, FieldValidateTriggerType } from '@douyinfe/semi-foundation/lib/cjs/form/interface';
import type { SelectProps } from '../select/index';
import Option from '../select/option';
import OptGroup from '../select/optionGroup';
import type { CheckboxProps } from '../checkbox/index';
import type { RadioProps } from '../radio/index';
import { ReactFieldError as FieldError } from './errorMessage';
import type { LabelProps } from './label';
export type { FormState, FormApi, WithFieldOption, RuleItem };
export type CommonFieldProps = {
    /** Field is required (except Form. Checkbox within the Group, Form. Radio) */
    field: string;
    /** The label text of the form control is the same name as the field by default when it is not passed */
    label?: LabelProps | React.ReactNode;
    labelPosition?: 'top' | 'left' | 'inset';
    labelAlign?: 'left' | 'right';
    labelWidth?: number | string;
    noLabel?: boolean;
    noErrorMessage?: boolean;
    name?: string;
    fieldClassName?: string;
    fieldStyle?: React.CSSProperties;
    initValue?: any;
    /**
     * Custom field validation function
     * @deprecated Use `validator` instead. This alias will be maintained for backward compatibility.
     */
    validate?: (fieldValue: any, values: Record<string, any>) => string | Promise<string>;
    /**
     * Custom field validation function (**recommended**)
     * @param fieldValue - The current field value
     * @param values - All form values
     * @returns Error message string, empty string for valid, or Promise that resolves to error message
     */
    validator?: (fieldValue: any, values: Record<string, any>) => string | Promise<string>;
    /** Check rules, check library based on async-validator */
    rules?: Array<RuleItem>;
    /** Check trigger timing */
    trigger?: 'blur' | 'change' | 'custom' | 'mount' | Array<string>;
    /** Converts form control values before validation */
    transform?: (fieldValue: any) => any;
    /** Make a second change to the component's value before the UI update */
    convert?: (fieldValue: any) => any;
    allowEmptyString?: boolean;
    /** When true, use rules verification, after encountering the first rule that fails the test, the verification of subsequent rules will no longer be triggered */
    stopValidateWithError?: boolean;
    helpText?: React.ReactNode;
    extraText?: React.ReactNode;
    extraTextPosition?: 'middle' | 'bottom';
    /** These declaration just hack for Omit, not valid props in CommonFieldProps */
    defaultValue?: any;
    /** Whether to take over only the data stream, when true, it will not automatically insert modules such as ErrorMessage, Label, extraText, etc. The style and DOM structure are consistent with the original component */
    pure?: boolean;
    /** Whether to retain field state (value, error, touched) after the field is unmounted. When the field remounts, the saved state will be restored */
    keepState?: boolean;
};
export type CommonexcludeType = {
    defaultValue?: any;
    value?: any;
    checked?: boolean;
    defaultChecked?: boolean;
};
export type RadioCheckboxExcludeProps = {
    defaultValue?: any;
    checked?: boolean;
    defaultChecked?: boolean;
    field: string;
};
export type RCIncludeType = {
    field?: string;
};
export declare class FormSelect extends React.Component<Omit<SelectProps & CommonFieldProps, keyof CommonexcludeType>> {
    static Option: typeof Option;
    static OptGroup: typeof OptGroup;
}
export interface SelectStatic {
    Option: typeof Option;
    OptGroup: typeof OptGroup;
}
export declare class Field<P> extends React.Component<Omit<P & CommonFieldProps, keyof CommonexcludeType> & React.RefAttributes<any>> {
}
export declare let FormSelectType: React.ComponentType<Omit<SelectProps & CommonFieldProps, keyof CommonexcludeType>> & SelectStatic;
export declare let FormCheckboxType: React.ComponentType<Omit<CommonFieldProps, keyof RadioCheckboxExcludeProps> & CheckboxProps & RCIncludeType>;
export declare let FormRadioType: React.ComponentType<Omit<CommonFieldProps, keyof RadioCheckboxExcludeProps> & RadioProps & RCIncludeType>;
export interface ErrorMsg {
    [optionalKey: string]: FieldError;
}
export interface FormFCChild<K extends Record<string, any> = any> {
    formState: FormState<K>;
    values: K;
    formApi: FormApi<K>;
}
type BatchValidateResult<Values> = string | Partial<AllErrors<Values>>;
export interface BaseFormProps<Values extends Record<string, any> = any> extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'children' | 'onChange' | 'onSubmit' | 'onReset'> {
    'aria-label'?: React.AriaAttributes['aria-label'];
    onSubmit?: (values: Values, e?: React.FormEvent<HTMLFormElement>) => void;
    onSubmitFail?: (errors: Record<keyof Values, FieldError>, values: Partial<Values>, e?: React.FormEvent<HTMLFormElement>) => void;
    onReset?: () => void;
    onValueChange?: (values: Values, changedValue: Partial<Values>) => void;
    onErrorChange?: (errors: Record<keyof Values, FieldError>, changedError?: Partial<Record<keyof Values, FieldError>>) => void;
    onChange?: (formState: FormState<Values>) => void;
    allowEmpty?: boolean;
    /**
     * Custom form-level validation function
     * @deprecated Use `validator` instead. This alias will be maintained for backward compatibility.
     */
    validateFields?: (values: Values) => BatchValidateResult<Values> | Promise<BatchValidateResult<Values>>;
    /**
     * Custom form-level validation function (**recommended**)
     * @param values - All form values
     * @returns Errors object with field names as keys, empty string for valid, or Promise that resolves to errors
     */
    validator?: (values: Values) => BatchValidateResult<Values> | Promise<BatchValidateResult<Values>>;
    /** Use this if you want to populate the form with initial values. */
    initValues?: Values;
    id?: string;
    /** getFormApi will be call once when Form mounted, u can save formApi reference in your component  */
    getFormApi?: (formApi: FormApi<Values>) => void;
    /** External formApi created by Form.useForm() */
    form?: any;
    style?: React.CSSProperties;
    className?: string;
    extraTextPosition?: 'middle' | 'bottom';
    layout?: 'horizontal' | 'vertical';
    labelPosition?: 'top' | 'left' | 'inset';
    labelWidth?: number | string;
    labelAlign?: 'left' | 'right';
    labelCol?: Record<string, any>;
    wrapperCol?: Record<string, any>;
    render?: (internalProps: FormFCChild<Values>) => React.ReactNode;
    component?: React.FC<any> | React.ComponentClass<any>;
    children?: React.ReactNode | ((internalProps: FormFCChild<Values>) => React.ReactNode);
    autoScrollToError?: boolean | ScrollIntoViewOptions;
    disabled?: boolean;
    showValidateIcon?: boolean;
    stopValidateWithError?: boolean;
    stopPropagation?: {
        submit?: boolean;
        reset?: boolean;
    };
    trigger?: FieldValidateTriggerType;
}