@n3/react-form-kit
v0.16.12
Published
Integration of @vtaits/react-final-form-schema and @n3/kit.
Downloads
187
Maintainers
Keywords
Readme
@n3/react-form-kit
Интеграция @vtaits/react-final-form-schema
с @n3/kit
Использование
Форма создания/редактирования
import { Button, buttonColors } from '@n3/kit';
import {
Form,
createFormFields,
BottomBlock,
ButtonsBlock,
} from '@n3/react-form-kit';
const fieldTypes = createFormFields(options);
const getFieldType = ({ type }) => fieldTypes[type];
...
<Form
{...otherFormProps}
names={[
'fieldName1',
'fieldName2',
'fieldName3',
]}
fields={fields}
getFieldType={getFieldType}
renderBottom={({
renderError,
submitting,
}) => (
<BottomBlock>
{renderError()}
<ButtonsBlock>
<Button
color={buttonColors.PRIMARY}
componentProps={{
type: 'submit',
}}
disabled={submitting}
>
Сохранить
</Button>
<Button
color={buttonColors.DEFAULT}
componentProps={{
type: 'button',
}}
disabled={submitting}
>
Отмена
</Button>
</ButtonsBlock>
</BottomBlock>
)}
/>
createFormFields options
Необязательное, объект, может содержать параметры:
get
- асинхронная функция get-запроса на сервер, принимает аргументы:url
- строка;queryParams
- объект параметров;
getFetchHeaders
- функция получения заголовков для вызоваfetch
;processUploadedAttachment
- функция процессинга файлов в полеattachment
, принимает аргументы:response
- ответ сервера в результате загрузки;file
- загруженный файл;
uploadAttachment
- асихнхронная функция загрузкий файлов в полеattachment
, принимает аргументы:file
- загруженный файл;schema
- схема поля;getFetchHeaders
- функция из параметров;processUploadedAttachment
- функция из параметров.
Form props
Принимает props @vtaits/react-final-form-schema
, а также добавляются:
fields
- необязательное, объект, ключами которого являются имена полей, а значениями - их схемы, работает только в случае, еслиgetFieldSchema
не задано;renderFields
- необязательное, функция рендера блока полей формы с помощьюrenderFieldsBlock
(смотри Form renderProps). Если не задано, поля будут отрендерены подряд одно за другим. ПринимаетrenderProps
формы.renderBottom
- необязательное, функция рендера контента ниже полей ввода (кнопки, сообщения об ошибках, не относящихся к полям, ...) с помощьюrenderBottomBlock
(смотри Form renderProps). ПринимаетrenderProps
формы.children
- необязательное, функция рендера формы. Если не задана, будут рендериться подряд результаты вызововrenderFieldsBlock
иrenderBottomBlock
;errorTitle
- необязательное, строка, заголовок сообщения о наличии ошибок формы;errorMessages
- необязательное, массив строк, тексты сообщений о наличии ошибок формы;excludeNames
- необязательное, массив имён полей, исключённых из рендера;errorsPath
- необязательное, строка, путь до объекта ошибок в случае неудачной отправки, по умолчанию"response.data"
;onSubmitSuccess
- необязательное, функция, обработчик успешной отправки формы, первым аргументом принимает результат вызоваonSubmit
;onSubmitError
- необязательное, функция, обработчик отправки формы с ошибкой;redirectTo
- необязательное, адрес редиректа после успешной отправки формы;getRedirectTo
- необязательное, функция получения адреса редиректа после успешной отправки формы, первым аргументом принимает результат вызоваonSubmit
;notification
- необязательное, объект, параметры вспывающего сообщенияsuccessLog
после успешной отправки формы;getNotification
- необязательное, функция получения параметров вспывающего сообщенияsuccessLog
после успешной отправки формы, первым аргументом принимает результат вызоваonSubmit
.
Form renderProps
Передаются все renderProps из @vtaits/react-final-form-schema
, а также добавляются следующие:
renderFieldsBlock
- функиця рендера полей формы;renderBottomBlock
- функция рендера контента ниже полей ввода;renderError
- функция рендера ошибки отправки формы;names
- спиок полей для рендера формы.
Ошибки формы
В отличие от final-form
, если функция onSubmit
не бросила исключение, отправка счиатется успешной. Есть способы вывести ошибки:
Бросить исключение
SubmissionError
:import { Form, SubmissionError } from '@n3/react-form-kit'; ... <Form onSubmit={async () => { throw new SubmissionError({ field1: ['Ошибка'], field2: ['Ошибка'], }); }} />
Бросить любое другое исключение, параметр
errorsPath
должен содержать путь до объекта ошибок, например, при использованииaxios
:import { Form } from '@n3/react-form-kit'; ... <Form onSubmit={async (values) => { await axios.post('/url/', values); }} errorsPath="response.data" />
Форма просмотра
import {
Form,
createShowFields,
} from '@n3/react-form-kit';
const showFieldTypes = createShowFields();
const getShowFieldType = ({ type }) => showFieldTypes[type];
...
<Form
{...otherFormProps}
names={[
'fieldName1',
'fieldName2',
'fieldName3',
]}
fields={fields}
getFieldType={getShowFieldType}
/>
Кастомное поле для формы создания/редактирования
Создаёт поле с выводом заголовка, ошибок, ворнингов, звёздочки в случае обязательности
import { FieldWrapper } from '@n3/react-form-kit';
const FieldComponent = (props) => {
...
return (
<FieldWrapper
{...props}
>
{({
input,
meta,
disabled,
hasError,
hasWarning,
name,
}) => {
...
}}
</FieldWrapper>
);
};
Кастомное поле для формы просмотра
Создаёт поле с выводом заголовка
import { ShowFieldWrapper } from '@n3/react-form-kit';
const FieldComponent = (props) => {
...
return (
<ShowFieldWrapper
{...props}
>
{({
input,
meta,
disabled,
hasError,
hasWarning,
name,
}) => {
...
}}
</ShowFieldWrapper>
);
};
Кастомный массив полей для формы создания/редактирования
Создаёт группу полей с выводом заголовка, ошибок, ворнингов, звёздочки в случае обязательности
import { FieldArrayWrapper } from '@n3/react-form-kit';
const FieldArrayComponent = (props) => {
...
return (
<FieldArrayWrapper
{...props}
>
{({
fields,
meta,
disabled,
hasError,
hasWarning,
name,
}) => {
...
}}
</FieldArrayWrapper>
);
};
Кастомный массив полей для формы просмотра
Создаёт группу полей с выводом заголовка
import { ShowFieldArrayWrapper } from '@n3/react-form-kit';
const FieldArrayComponent = (props) => {
...
return (
<ShowFieldArrayWrapper
{...props}
>
{({
fields,
meta,
disabled,
hasError,
hasWarning,
name,
}) => {
...
}}
</ShowFieldArrayWrapper>
);
};
Повторяющиеся группы полей с кнопками добавления и удаления
RepeatWrapper
Аналогично FieldArrayWrapper
, но добавляются функции handleAdd
и handleRemove
.
import { RepeatWrapper } from '@n3/react-form-kit';
const RepeatComponent = (props) => {
...
return (
<RepeatWrapper
{...props}
fieldSchema={{
required,
initialValues,
}}
>
{({
fields,
meta,
disabled,
hasError,
hasWarning,
handleAdd,
handleRemove,
name,
}) => {
...
}}
</RepeatWrapper>
);
};
handleAdd
- функция, при вызове добавляет новую группу полей со значениямиinitialValues
;handleRemove
- функция, удаляет группу полей по выбранному индексу. Если группа была единственная, а такжеrequired
= true, то добавляет новую группу полей сinitialValues
.
useRepeat
Хук для создания повторяющихся групп полей на основе useFieldArray
из react-final-form-arrays
.
import { useRepeat } from '@n3/react-form-kit';
const RepeatField = ({
name,
initialValues,
required,
}) => {
const {
fields,
meta,
handleAdd,
handleRemove,
} = useRepeat(name, {
required,
initialValues,
});
const removeByIndex = (index) => {
handleRemove(index);
};
}
Аналогично useFieldArray
, но добавляются функции добавления и удаления групп полей.
handleAdd
- функция, при вызове добавляет новую группу полей со значениямиinitialValues
;handleRemove
- функция, удаляет группу полей по выбранному индексу. Если группа была единственная, а такжеrequired
= true, то добавляет новую группу полей сinitialValues
.
Схема полей
Каждое поле, созданное при помощи createField
или createShowField
имеет следующие необязательные параметры:
label
- строка, заголовок поля;onlyField
- булево, если true, заголовок поля не отображается;required
- булево, если true, на форме создания/редактирования рядом с заголовком отображается*
;help_text
- строка, подсказка, выводящаяся под полем;help_tooltip
- строка, подсказка, выводящаяся в тултипе рядом с заголовком;unit
- React.Node, единицы измерения;initial
- значение поля по умолчанию;labelCols
- число, количество колонок, которое занимает заголовок поля, по умолчанию 3;fieldCols
- число, количество колонок, которое занимает поле, по умолчанию 5;unitCols
- число, количество колонок, которое занимает блок единиц измерения, по умолчанию 1.
Реализованные поля
string
Поле ввода текста. Параметры:
inputComponent
- react-компонент, компонент поля, по умолчаниюinput
;inputType
- строка, тип инпута, по умолчаниюtext
;inputProps
- обеъект, дополнительные props элементаinput
;debounceTimeout
- задержка debounce-инпута, по умолчанию300
;max_length
- число, максимальное количество введённых символов;mask
- маска формата react-input-mask, если задано, параметрыdebounceTimeout
иmax_length
не работают;disabled
- булево;read_only
- булево;placeholder
- строка.
Полностью аналогично string
.
url
Полностью аналогично string
.
integer
Аналогично string
, отличия:
- отсутствие свойства
mask
; - сериализация пустого значения в
null
.
choice
Список опций для выбора. Параметры:
choices
- массив объектов опций селекта, по умолчанию имеют формат{ value, display_name }
, гдеvalue
- значение, отправляемое на сервер,label
- текст для отображения опции;valueKey
- ключ значения опции для отправки на сервер, по умолчаниюvalue
;labelKey
- ключ значения опции для отображения, по умолчаниюdisplay_name
;disabled
- булево;read_only
- булево;renderWith
-'select'
или'radio'
, по умолчанию'select'
.
multiple_choice
Мультиселект. Аналогичен choice
, но принимает и отправляет массивы значений. Параметры:
renderWith
-'select'
или'checkbox'
, по умолчанию'select'
.
ajax_choice
Селект с подгрузкой опций с сервера. Использует компонент SelectAjax
. Параметры:
choices_url
- строка, url для запроса данных. Опции могут приходить массивом или в форматеdrf
({ results, next }
);mapResponse
- необязательное, функция маппинга ответа сервера в форматreact-select-async-paginate
;queryParams
- объект параметров запроса, не зависящих от других полей;debounceTimeout
- задержка перед запросом в мс, по умолчанию300
;choices_cascade_params
- объект, ключами которого являются имена других полей, а значениями - названия параметров, под которыми они будут переданы на сервер;disabledWithoutCascadeValues
- булево, выключать ли поле в случае незаполненности хотя бы одного из полейchoices_cascade_params
;searchParamName
- строка, параметрSelectAjax
;pageParamName
- строка, параметрSelectAjax
;offsetParamName
- строка, параметрSelectAjax
;parseValue
- необязательное, функция загрузки опции по id. По умолчанию делается запрос на<choices_url><id>/
с параметрамиqueryParams
. Принимает аргументы;get
- из параметровcreateFormFields
;value
- id опции;choicesUrl
queryParams
mapResponseSimple
- смотри ниже;
mapResponseSimple
- необязательное, функция маппинга загруженного значения при парсинге в опцию.
ajax_multiple_choice
Мультиселект с подгрузкой опций с сервера. Аналогичен ajax_choice
, но принимает и отправляет массивы значений.
date
Дейтпикер. Принимает значения в формате js-объекта Date
, строки формата 2018-12-26
или строки формата 2018-10-14T22:33:20
. Параметры:
disabled
- булево;read_only
- булево.
datetime
Дейттаймпикер. Принимает значения в формате js-объекта Date
или строки формата 2018-10-14T22:33:20
. Параметры:
disabled
- булево;read_only
- булево.
boolean
Чекбокс. Принимает булевы значения. Параметры:
disabled
- булево;checkboxLabel
- строка, текст чекбокса;falsyLabel
- строка, используется для вывода ложного значения на форме просмотра;truthyLabel
- строка, используется для вывода истинного значения на форме просмотра.
phone
Поле ввода телефона с маской.
time
Поле ввода времени с маской.
attachment
Загрузчик файлов по схемам drf
. Параметры:
upload_url
- обязательное, url для загрузки файла;upload_field
- необязательное, ключ, по которому загруженный файл будет передан на сервер, по умолчанию'tmpfile'
;allowed_extensions
- необязательное, список доступных расширений ([".docx", ".pdf", ".xlsx"]
);max_length
- необязательное, максимальное количество файлов;max_size
- необязательное, максимальный размер файла в байтах;isDragAndDrop
- необязательное, из компонентаFileUploader
.
file
Загрузчик одного файла. Параметры:
uploadFile
- обязательное, асинхронная функция загрузки файла@n3/react-fileuploader
;extensions
- необязательное, массив возможных расширений файлов;placeholder
- необязательное, react node, текст загрузчика;isDragAndDrop
- необязательное, из компонентаFileUploader
.
multiple_file
Загрузчик нескольких файлов. Параметры:
uploadFile
- обязательное, асинхронная функция загрузки файла@n3/react-fileuploader
;extensions
- необязательное, массив возможных расширений файлов;placeholder
- необязательное, react node, текст загрузчика;maxLength
- необязательное, число, максимальное количество файлов;isDragAndDrop
- необязательное, из компонентаFileUploader
.
nested_object
Группа полей. Параметры:
child
- обязательное, объект, поля:fields
- обязательное, объект, схемы полея группы;ordering
- обязательное, массив, список имён полей группы;
excludeNames
- необязательное, массив полей, которые нужно исключить изordering
;render
- необязательное, функция рендера содержимого блока. Пример:render: ({ renderField, ordering, }) => ( <> {renderField('nestedField1')} {renderField('nestedField2')} </> )
renderField
- функция рендера вложенного поля по имени;ordering
- массив имён вложенных полей, из которого исключеныexcludeNames
.
list
Повторяющееся поле. Параметры:
child
- обязательное, объект, схема повторяющегося поля;addButtonTitle
- необязательное, текст кнопки добавления, по умолчанию'Добавить ещё'
;getBlockTitle
- необязательное, функция генерации заголовка блока, принимает аргументы:index
- число, индекс блока в списке;
blockTitle
- необязательное, заголовок каждого блока, работает в случае, если не определеноgetBlockTitle
;style
- необязательное,'default' | 'mini'
, стиль блоков;min_length
- необязательное, минимальное количество элементов;max_length
- необязательное, максимальное количество элементов;
nested_objects_list
Повторяющаяся группа полей. Параметры:
child
- обязательное, объект, поля:fields
- обязательное, объект, схемы полей группы;ordering
- обязательное, массив, список имён полей группы;
excludeNames
- необязательное, массив полей, которые нужно исключить изordering
;addButtonTitle
- необязательное, текст кнопки добавления, по умолчанию'Добавить ещё'
;getBlockTitle
- необязательное, функция генерации заголовка группы полей, принимает аргументы:index
- число, индекс группы полей в списке;
blockTitle
- необязательное, заголовок каждой группы полей, работает в случае, если не определеноgetBlockTitle
;renderBlock
- необязательное, функция рендера содержимого блока. Пример:renderBlock: ({ renderField, ordering, }) => ( <> {renderField('nestedField1')} {renderField('nestedField2')} </> )
renderField
- функция рендера вложенного поля по имени;ordering
- массив имён вложенных полей, из которого исключеныexcludeNames
.
style
- необязательное,'default' | 'mini'
, стиль блоков;min_length
- необязательное, минимальное количество элементов;max_length
- необязательное, максимальное количество элементов;
dynamic
Поле со схемой, зависящей от других полей. Пример:
const schema = {
type: 'dynamic',
getSchema: ({
otherField,
}, phase) => ({
type: 'string',
label: 'Поле',
required: Boolean(otherField),
}),
};
Параметры:
getSchema
- обязательное, функция, первым аргументом принимает объект значений формы. Должна вернуть схему поля для рендера илиnull
. В случае возвратаnull
поле не отображается и не участвует в сериализации и парсинге значений формы, а также сборе ошибок. Аргументы;values
- объект значений формы на этапе рендера/сериализации или объект необработанных значений на этапе парсинга;phase
- текущая фаза @vtaits/form-schema. Принимает значения:'parse'
,'serialize'
,'render'
;
getSchemaAsync
- необязательное, функция. Может быть использована для асинхронного парсинга. АналогичнаgetSchema
, но должна вернутьPromise
с итоговой схемой;onShow
- необязательное, функиця. которая вызывается после показа поля. Аргументы:form
- экземплярfinal-form
;name
- имя поля;schema
- схема дочернего поля;getFieldSchema
- текущееgetFieldSchema
;getFieldType
- глобальноеgetFieldType
;parents
- массив родительских полей;
onHide
- not required, callback that called when field has hidden. Arguments:form
- экземплярfinal-form
;name
- имя поля;getFieldSchema
- текущееgetFieldSchema
;getFieldType
- глобальноеgetFieldType
;parents
- массив родительских полей.
Вспомогательные компоненты
BottomBlock
Контейнер для вывода блоков ошибок и кнопок.
props
| Название | Обязательность | Тип | Значение по умолчанию | Описание |
|----------|----------------|-----|-----------------------|----------|
| hasSections | | bool | false
| Поля формы сгруппированы в секции с заголовками слева |
| children | | node | null
| |
ButtonsBlock
Контейнер для кнопок действий.
SubmitButtonByType
Кнопка для создания форм с несколькими способами отправки.
props
| Название | Обязательность | Тип | Значение по умолчанию | Описание |
|----------|----------------|-----|-----------------------|----------|
| handleSubmit | + | () => void
| | Функция отправки формы react-final-form
|
| submitTypeRef | + | MutableRefObject<any>
| | ref
для установки способа отправки |
| submitType | + | any
| | Способ отправки формы |
Утилиты
getErrorsAndWarnings
import { getErrorsAndWarnings } from '@n3/react-form-kit';
...
const {
errors,
warnings,
} = getErrorsAndWarnings(submitError);
Функция для получения списков ошибок и предупреждений по стандартной ошибке поля.
Конфигурация через FormConfigContext
import { FormConfigContext } from '@n3/react-form-kit';
<FormConfigContext.Provider
value={{
labelCols: 4,
fieldCols: 8,
onFieldChange: (value, prevValue, name, form) => {
// ...
},
}}
>
{/** ... */}
</FormConfigContext.Provider>
isCellsPercentage
- необязательное,boolean
, пропорциональная ширина поля и контейнера для единиц измерения;labelCols
- обязательное, число, количество колонок заголовков по умолчанию;fieldCols
- обязательное, число, количество колонок полей по умолчанию;colon
- необязательное,boolean
, показывать ли двоеточие после заголовка поля;direction
- необязательное,'horizontal' | 'vertical'
, направление рендера полей;onFieldChange
- необязательное, функция, глобальный обработчик изменений значений полей.