@n3/react-form-builder
React-компонент для построения форм по схеме. Для работы с состоянием используется final-form
.
Установка
npm install @n3/react-form-builder
или
yarn add @n3/react-form-builder
Использование
import { Form } from '@n3/react-form-builder';
// ...
<Form
onSubmit={onSubmit}
initialValues={initialValues}
schema={schema}
getFieldSchema={getFieldSchema}
getFieldType={getFieldType}
errorsPath={errorsPath}
mapErrors={mapErrors}
formProps={formProps}
renderError={renderError}
renderWarning={renderWarning}
renderButtons={renderButtons}
layoutComponent={layoutComponent}
onFieldChange={onFieldChange}
{...otherProps}
/>
Props
-
onSubmit
- обязательное, функция, аналогичнаreact-final-form
, отличия:-
первым аргументом принимает сериализованные значения формы, а вторым - оригинальные значения
final-form
; -
ошибки могут быть возвращены в объекте, а могут возвразаться через
throw
;
-
-
onFieldChange
- необязательное, функция срабатывает при изменении значения поля, аргументы:-
value
- значение поля; -
prevValue
- предыдущее значение поля; -
path
- путь до поля; -
form
- экземпляр формы final-form;
-
-
initialValues
- необязательное, объект, аналогиченreact-final-form
, но перед передачей в форму обрабатывается полями схемы; -
schema
- обязательное, массив, содержит элементы, по каждому из которых будет получена схема поля с помощью функцииgetFieldSchema
; -
parents
- обязательное, массив, элементами являются объекты с параметрами:-
name
- необязательное, строка. Для корневого элемента (формы) отсутствует, для вложенных полей - имя группирующего поля; -
values
- обязательное, объект, значения текущего группируюшего поля;
-
-
getFieldSchema
- необязательное, функция маппинга элементовschema
в схему поля; -
getFieldType
- обязательное, функция получения типа поля по схеме поля, должна возвращать объект формата:-
createGetFieldSchema
- необязательное, функция для переопределенияgetFieldSchema
на уровне компонента поля и мапперов, принимает аргументы:-
fieldSchema
- схема поля; -
getFieldSchema
-getFieldSchema
родительского элемента или формы; -
getFieldType
- из компонентаForm
; -
values
- объект значений формы на этапе рендера/сериализации или объект необработанных значений на этапе парсинга; -
phase
-'parse'
,'serialize'
или'render'
; -
parents
- смотри выше;
-
-
component
- обязательное, react-компонент поля формы. Принимает в качестве props схему поля, а также дополнительныеprops
:-
getFieldSchema
- обязательное, смотри выше; -
getFieldType
- обязательное, из компонентаForm
; -
onFieldChange
- обязательное, функция из компоентаForm
, но без аргументаchange
; -
renderField
- обязательное, функция рендера дочернего компонента по имени, аргументы:-
name
- имя вложенного поля; -
member
- префекс имени вложенного поля (для массивов и групп полей);
-
-
-
valueMapper
- необязательное, функция, определяющая, как поле будет передваться вonSubmit
, аргументы:-
values
- объект значений формы; -
fieldSchema
- схема поля; -
getFieldSchema
- смотри выше; -
getFieldType
- смотри выше; -
parents
- смотри выше;
должна возвращать обеъкт значений для отправки. По умолчанию отправляет только значение из
values
по ключу"name"
из схемы формы; -
-
valueParser
- необязательное, функция, определяющая, как поле будет определять своё значение для инициализации, аргументы:-
initialValues
- из компонентаForm
; -
fieldSchema
- схема поля; -
getFieldSchema
- смотри выше; -
getFieldType
- смотри выше; -
parents
- смотри выше;
должна возвращать обеъкт значений. По умолчанию возвращает только значение из
initialValues
по ключу"name"
из схемы формы. Может быть асинхронной; -
-
errorsMapper
- необязательное, функция, определяющая, как поле будет переводить ошибки сабмита в свой формат, аргументы:-
errors
- объект ошибок; -
fieldSchema
- схема поля; -
getFieldSchema
- смотри выше; -
getFieldType
- смотри выше; -
values
- значения полей формы после обработки; -
rawValues
- значения полей формы; -
parents
- смотри выше, в качестве значений использует сериализованные значения формы;
должна возвращать обеъкт значений. По умолчанию возвращает только значение из
errors
по ключу"name"
из схемы формы; -
-
memberMapper
- необязательное, функция, процессор схемы для случая, когда поле вложено в другое поле (например, оно находится внутри группы полейFieldArray
):-
member
- префикс имени поля; -
fieldSchema
- схема поля; -
getFieldSchema
- смотри выше; -
getFieldType
- смотри выше;
должна возвращать новую схему. По умолчанию возвращает
fieldSchema
с переопределённымname
, равным${member}.${fieldSchema.name}
; -
-
-
errorsPath
- необязательное, строка, в случае ошибки отправки определяет путь до объекта ошибки, по умолчанию"response.data"
(axios
); -
mapErrors
- необязательное, функция, в случае ошибки отправки обрабатывает объект ошибки перед вызовомSubmissionError
, по умолчанию переделываетnon_field_errors
иdetail
в_error
. Принимает аргументы:-
errors
- оригинальный объект ошибок; -
values
- значения полей формы после обработки; -
rawValues
- значения полей формы;
-
-
getError
- необязательное, функция получения ошибки по объектуerror
. По умолчанию возвращает полностьюerror
. Может быть использована для вывода ошибок и предупреждений; -
getWarning
- необязательное, функция получения ошибки по объектуerror
. По умолчанию возвращает null. Может быть использована для вывода ошибок и предупреждений; -
renderFields
- необязательное, функция рендера полей формы, принимает все render propsreact-final-form
, а также дополнителноеrenderField
для рендера поля по имени, пример использования:renderFields={({ submitting, renderField, }) => ( <> <ul> <li> {renderField('input')} </li> <li> {renderField('requiredInput')} </li> <li> {renderField('select')} </li> <li> {renderField('date')} </li> </ul> { submitting && ( <p> Submitting... </p> ) } </> )}
-
renderError
- необязательное, функция, должна вернуть реакт-элемент ошибки формы. Первым аргументом принимает ошибку. По умолчанию отображает красный текст; -
renderWarning
- необязательное, функция, должна вернуть реакт-элемент предупреждения формы. Первым аргументом принимает предупреждение. По умолчанию отображает тёмно-оранжевый текст; -
renderButtons
- необязательное, функция, должна вернуть реакт-элемент кнопок формы. Первым аргументом принимает объект, содержащий функцииform
(экземпляр формы final-form) и функциюhandleSubmit
(смотри react-final-form). По умолчанию отображает submit-кнопку; -
formProps
- необязательное, объект, дополнительныеprops
компонента<form>
, например,noValidate
; -
layoutComponent
- необязательное, react-компонент, кастомный лэйаут формы. Принимаетprops
:-
formProps
- из компонентаForm
; -
formFields
- обязательное, react-элемент, блок полей формы; -
error
- необязательное, react-элемент, блок ошибок; -
warning
- необязательное, react-элемент, блок предупреждений; -
buttons
- необязательное, react-элемент, блок кнопок; -
handleSubmit
- смотри react-final-form.
-
Утилиты
ARRAY_ERROR
import { ARRAY_ERROR } from '@n3/react-form-builder';
Смотри final-form
FORM_ERROR
import { FORM_ERROR } from '@n3/react-form-builder';
Смотри final-form
useForm
import { useForm } from '@n3/react-form-builder';
Смотри react-final-form
useFormState
import { useFormState } from '@n3/react-form-builder';
Смотри react-final-form
useField
import { useField } from '@n3/react-form-builder';
const Field = ({
name,
onFieldChange,
}) => {
const {
input,
meta,
} = useField(name, {
onFieldChange,
});
// ...
}
Аналогично react-final-form, но в объект параметров должно принимать onFieldChange
, который передаётся полю через props
.
Аргументы onFieldChange
:
-
nextValue
- значение поля после изменения; -
prevValue
- значение поля до изменения; -
name
- имя поля; -
form
- экземплярfinal-form
.
useFieldArray
import { useFieldArray } from '@n3/react-form-builder';
Смотри react-final-form-arrays
useRepeat
Хук для создания повторяющихся групп полей на основе useFieldArray
.
import { useRepeat } from '@n3/react-form-builder';
const RepeatField = ({
name,
initialValues,
required,
}) => {
const {
fields,
meta,
handleAdd,
handleRemove,
} = useRepeat(name, {
onFieldChange,
});
const removeByIndex = (index) => {
handleRemove(index);
};
// ...
}
Аналогично useFieldArray
, но добавляются хендлеры добавления и удаления групп полей.
-
handleAdd
- функция, при вызове добавляет новую группу полей со значениямиinitialValues
; -
handleRemove
- функция, удаляет группу полей по выбранному индексу. Если группа была единственная, а такжеrequired
= true, то добавляет новую группу полей сinitialValues
.
useFormSchemaState
import { useFormSchemaState } from '@n3/react-form-builder';
Смотри @vtaits/react-final-form-schema
Утилиты
serialize
parse
mapFieldErrors
validateBeforeSubmit
Смотри @vtaits/form-schema