@alifd/field
Version:
Fields can be used to manage data when it comes to form data manipulation and validation. After being associated with a component, the form data can be automatically written back, read, and verified.
215 lines (214 loc) • 9.2 kB
TypeScript
import { type NormalizedValidateError } from '@alifd/validate';
import type { FieldOption, ComponentInstance, GetUseFieldOption, FieldMeta, RerenderFunction, WatchCallback, NormalizedFieldOption, InitOption, FieldValues, NormalizedFieldMeta, Rule, FieldState, ValidateCallback, ValidateErrorGroup, RerenderType, WatchTriggerType, ValidatePromiseResults } from './types';
declare class Field {
static create(com: ComponentInstance, options?: FieldOption): Field;
static getUseField({ useState, useMemo }: GetUseFieldOption): (options?: FieldOption) => Field;
fieldsMeta: Record<string, FieldMeta>;
cachedBind: Record<string, Record<string, unknown>>;
instance: Record<string, unknown>;
instanceCount: Record<string, number>;
reRenders: Record<string, RerenderFunction>;
listeners: Record<string, Set<WatchCallback>>;
values: FieldValues;
processErrorMessage?: FieldOption['processErrorMessage'];
afterValidateRerender?: FieldOption['afterValidateRerender'];
com: ComponentInstance;
options: NormalizedFieldOption;
constructor(com: ComponentInstance, options?: FieldOption);
/**
* 设置配置信息
* @param options - 配置
*/
setOptions(options: Partial<FieldOption>): void;
/**
* 初始化一个字段项
* @param name - 字段 key
* @param option - 字段配置
* @param rprops - 其它参数
*/
init<ValueType = any, ValueName extends string = 'value', Trigger extends string = 'onChange', OtherProps extends object = object>(name: string, option?: InitOption<ValueType, ValueName, Trigger, OtherProps>, rprops?: OtherProps): OtherProps & {
'data-meta': "Field";
id: string;
ref: (instance: any) => void;
} & { [k in Exclude<ValueName, Trigger>]: ValueType; } & { [k_1 in Exclude<Trigger, ValueName>]: import("./types").TriggerFunction; };
/**
* 获取单个输入控件的值
* @param name - 字段名
* @returns 字段值
*/
getValue<T = unknown>(name: string): T | undefined;
/**
* 获取一组输入控件的值
* @param names - 字段名数组
* @returns 不传入`names`参数，则获取全部字段的值
*/
getValues<T = Record<string, unknown>>(names?: string[]): T;
/**
* 设置单个输入控件的值（默认会触发 render，请遵循 react 时机使用)
* @param name - 字段名
* @param value - 字段值
* @param reRender - 设置完成后是否重新渲染，默认为 true
* @param triggerChange - 是否触发 watch change，默认为 true
*/
setValue<T = unknown>(name: string, value: T, reRender?: boolean, triggerChange?: boolean): void;
/**
* 设置一组输入控件的值（默认会触发 render，请遵循 react 时机使用)
* @param fieldsValue - 一组输入控件值对象
* @param reRender - 设置完成后是否重新渲染，默认为 true
*/
setValues(fieldsValue?: Record<string, unknown>, reRender?: boolean): void;
/**
* 获取单个输入控件的 Error
* @param name - 字段名
* @returns 该字段的 Error
*/
getError(name: string): unknown[] | null;
/**
* 获取一组输入控件的 Error
* @param names - 字段名列表
* @returns 不传入`names`参数，则获取全部字段的 Error
*/
getErrors<K extends string>(names?: K[]): Record<K, unknown[] | null>;
/**
* 设置单个输入控件的 Error
* @param name - 字段名
* @param errors - 错误信息
*/
setError(name: string, errors?: unknown): void;
/**
* 设置一组输入控件的 Error
*/
setErrors(fieldsErrors?: Record<string, unknown>): void;
/**
* 获取单个字段的校验状态
* @param name - 字段名
*/
getState(name: string): FieldState;
/**
* 校验全部字段
* @param callback - 校验结果的回调函数
*/
validateCallback(callback?: ValidateCallback): void;
/**
* 校验指定字段
* @param names - 字段名或字段名列表
* @param callback - 校验结果回调函数
*/
validateCallback(names?: string | string[], callback?: ValidateCallback): void;
/**
* Promise 方式校验全部字段
*/
validatePromise(): Promise<ValidatePromiseResults>;
/**
* Promise 方式校验指定字段
* @param names - 字段名或字段名列表
*/
validatePromise(names?: string | string[]): Promise<ValidatePromiseResults>;
/**
* Promise 方式校验所有字段，并使用一个函数处理校验结果
* @param formatter - 校验结果处理函数
*/
validatePromise<FormatterResults>(formatter?: (results: ValidatePromiseResults) => FormatterResults | Promise<FormatterResults>): Promise<FormatterResults>;
/**
* Promise 方式校验指定字段，并使用一个函数处理校验结果
* @param names - 字段名或字段名列表
* @param formatter - 校验结果处理函数
*/
validatePromise<FormatterResults>(names?: string | string[], formatter?: (results: ValidatePromiseResults) => FormatterResults | Promise<FormatterResults>): Promise<typeof formatter extends undefined ? ValidatePromiseResults : FormatterResults>;
/**
* 重置一组输入控件的值，并清空校验信息
* @param names - 要重置的字段名，不传递则重置全部字段
*/
reset(ns?: string | string[]): void;
/**
* 重置一组输入控件的值为默认值，并清空校验信息
* @param names - 要重置的字段名，不传递则重置全部字段
*/
resetToDefault(ns?: string | string[]): void;
/**
* 获取所有字段名列表
*/
getNames(): string[];
/**
* 删除某一个或者一组控件的数据，删除后与之相关的 validate/value 都会被清空
* @param name - 要删除的字段名，不传递则删除全部字段
*/
remove(ns?: string | string[]): void;
/**
* 向指定数组字段内添加数据
* @param name - 字段名
* @param index - 开始添加的索引
* @param argv - 新增的数据
*/
addArrayValue(name: string, index: number, ...argv: unknown[]): void;
/**
* 删除指定字段数组内的数据
* @param name - 变量名
* @param index - 开始删除的索引
* @param howmany - 删除几个数据，默认为 1
*/
deleteArrayValue(name: string, index: number, howmany?: number): void;
/**
* splice in a Array [deprecated]
* @deprecated Use `addArrayValue` or `deleteArrayValue` instead
* @param keyMatch - like name.\{index\}
* @param startIndex - index
*/
spliceArray(keyMatch: string, startIndex: number): void;
/**
* 获取全部字段信息
* @param name - 传递 falsy 值
*/
get(name?: undefined | ''): Record<string, NormalizedFieldMeta>;
/**
* 获取指定字段信息
* @param name - 字段名
*/
get(name: string): NormalizedFieldMeta | null;
/**
* 监听字段值变化
* @param names - 监听的 name 列表
* @param callback - 变化回调
* @returns 解除监听回调
*/
watch(names: string[], callback: WatchCallback): () => void;
_get(name: string): FieldMeta | null;
_getInitMeta(name: string): FieldMeta;
_getErrorsGroup({ errors, fieldNames }: {
errors: NormalizedValidateError[];
fieldNames: string[];
}): ValidateErrorGroup | null;
_reset(ns?: string | string[], backToDefault?: boolean): void;
_resetError(name: string): void;
_reRender(name?: string | string[], action?: RerenderType | string): void;
/**
* Get errors using `getErrors` and format to match the structure of errors returned in field.validate
*/
formatGetErrors(names?: string[]): ValidateErrorGroup | null;
/**
* call native event from props.onXx
* eg: props.onChange props.onBlur props.onFocus
*/
_callNativePropsEvent(action: string, props: Record<string, unknown>, ...args: unknown[]): void;
_proxyFieldValue(field: NormalizedFieldMeta): void;
/**
* update field.value and validate
*/
_updateFieldValue(name: string, ...others: unknown[]): void;
/**
* ref must always be the same function, or if not it will be triggerd every time.
*/
_getCacheBind<Args extends unknown[], Result>(name: string, action: string, fn: (name: string, ...args: Args) => Result): (...args: Args) => Result;
_setCache(name: string, action: string, hander: unknown): void;
_getCache<R = unknown>(name: string, action: string): R | undefined;
_saveRef(name: string, component: unknown): void;
_validate(name: string, rule: Rule[], trigger: string): void;
/**
* splice array
*/
_spliceArrayValue(key: string, index: number, howmany: number, ...argv: unknown[]): void;
_triggerFieldChange(name: string, value: unknown, oldValue: unknown, triggerType: WatchTriggerType): void;
_triggerAfterValidateRerender(errorsGroup: ValidateErrorGroup | null): void;
}
export * from './types';
export default Field;