@n3/react-form-kit

Поля для @n3/react-form-builder, стилизованные с помощью @n3/kit

Использование

Форма создания/редактирования

import { Form } from '@n3/react-form-builder';
import { createFields } from '@n3/react-form-kit';

const fieldTypes = createFields(options);

const getFieldType = ({ type }) => fieldTypes[type];

...

<Form
  {...otherFormProps}
  getFieldType={getFieldType}
/>

options - необязательное, объект, может содержать параметры:

• get - асинхронная функция get-запроса на сервер, принимает аргументы:

  • url - строка;

  • queryParams - объект параметров.

Форма просмотра

import { Form } from '@n3/react-form-builder';
import { createShowFields } from '@n3/react-form-kit';

const showFieldTypes = createShowFields();

const getShowFieldType = ({ type }) => showFieldTypes[type];

...

<Form
  {...otherFormProps}
  getFieldType={getShowFieldType}
/>

Кастомное поле для формы создания/редактирования

Создаёт поле с выводом заголовка, ошибок, ворнингов, звёздочек в случае обязательности

import { FieldWrapper } from '@n3/react-form-kit';

const FieldComponent = (props) => {
  ...

  return (
    <FieldWrapper
      {...props}
    >
      {({
        input,
        meta,
        disabled,
        hasError,
        hasWarning,
      }) => {
        ...
      }}
    </FieldWrapper>
  );
};

Кастомное поле для формы просмотра

Создаёт поле с выводом заголовка, ошибок и ворнингов

import { ShowFieldWrapper } from '@n3/react-form-kit';

const FieldComponent = (props) => {
  ...

  return (
    <ShowFieldWrapper
      {...props}
    >
      {({
        input,
        meta,
        disabled,
        hasError,
        hasWarning,
      }) => {
        ...
      }}
    </ShowFieldWrapper>
  );
};

Схема полей

Каждое поле, созданное при помощи createField или createShowField иммеет следующие необязательные параметры:

• label - строка, заголовок поля;

• onlyField - булево, если true, заголовок поля не отображается;

• required - булево, если true, на форме создания/редактирования рядом с заголовком отображается *;

• help_text - строка, подсказка поля;

• initial - значение поля по умолчанию;

• labelCols - число, количество колонок, которое занимает заголовок поля, по умолчанию 3;

• fieldCols - число, количество колонок, которое занимает поле, по умолчанию 5.

Реализованные поля

string

Поле ввода текста. Параметры:

• inputComponent - react-компонент, компонент поля, по умолчанию input;

• inputType - строка, тип инпута, по умолчанию text;

• debounceTimeout - задержка debounce-инпута, по умолчанию 300;

• max_length - число, максимальное количество введённых символов;

• mask - маска формата react-input-mask, если задано, параметры debounceTimeout и max_length не работают;

• disabled - булево;

• read_only - булево;

• placeholder - строка.

url

Полностью аналогично string.

choice

Селект. Параметры:

• choices - массив объектов опций селекта, по умолчанию имеют формат { value, display_name }, где value - значение, отправляемое на сервер, label - текст для отображения опции;

• valueKey - ключ значения опции для отправки на сервер, по умолчанию value;

• labelKey - ключ значения опции для отображения, по умолчанию display_name;

• disabled - булево;

• read_only - булево.

multiple_choice

Мультиселект. Аналогичен choice, но принимает и отправляет массивы значений.

ajax_choice

Селект с подгрузкой опций с сервера. Использует компонент SelectAjax. Параметры:

• choices_url - строка, url для запроса данных, ответ сервера должен быть в стандартном drf-формате ({ results, next });

• queryParams - объект параметров запроса, не зависящих от других полей;

• debounceTimeout - задержка перед запросом в мс, по умолчанию 300;

• choices_cascade_params - объект, ключами которого являются имена других полей, а значениями - названия параметров, под которыми они будут переданы на сервер;

• isClearOnChange- булево, сбросить ли значение поля при изменении зависимостей;

• parseValue - необязательное, функция загрузки опции по id. По умолчанию делается запрос на <choices_url><id>/ с параметрами queryParams. Принимает аргументы;

  1. get - из параметров createFields;

  2. value - id опции;

  3. choicesUrl

  4. queryParams

  5. 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 - булево;

• falsyLabel - строка, используется для вывода ложного значения на форме просмотра;

• truthyLabel - строка, используется для вывода истинного значения на форме просмотра.

dynamic

Поле со схемой, зависящей от других полей. Пример:

const schema = {
  type: 'dynamic',

  getSchema: ({
    otherField,
  }, phase) => ({
    type: 'string',
    label: 'Поле',
    required: Boolean(otherField),
  }),
};

Параметры:

• getSchema - обязательное, функция, первым аргументом принимает объект значений формы. Должна вернуть схему поля для рендера или null. В случае возврата null поле не отображается и не участвует в сериализации и парсинге значений формы, а также сборе ошибок. Аргументы:

  1. values - объект значений формы на этапе рендера/сериализации или объект необработанных значений на этапе парсинга;

  2. phase - текущая фаза @vtaits/form-schema. Принимает значения: 'parse', 'serialize', 'render';

  3. getFieldSchema - смотри @n3/react-form-builder;

  4. getFieldType - смотри @n3/react-form-builder.

Рендер ошибок и ворнингов

Выводит компонент Alert из @n3/kit.

import { Form } from '@n3/react-form-builder';
import { renderError, renderWarning } from '@n3/react-form-kit';

<Form
  {...otherFormProps}
  renderError={renderError}
  renderWarning={renderWarning}
/>

Поддерживают следующие форматы ошибки/ворнинга:

• строка
• массив строк
• массив объектов вида { message }, где message - строка
• объект вида { title, messages }, где title - строка, messages - массив строк или массив объектов вида { message }, где message - строка

Конфигурация через FormConfigContext

<FormConfigContext.Provider
  value={{
    labelCols: 4,
    fieldCols: 8,
    onFieldChange: (value, prevValue, name, form) => {
      // ...
    },
  }}
>
  {/** ... */}
</FormConfigContext.Provider>

• labelCols - обязательное, число, количество колонок заголовков по умолчанию;
• fieldCols - обязательное, число, количество колонок полей по умолчанию;
• onFieldChange - необязательное, функция, глобальный обработчик изменений значений полей.