Динамические формы V
Last updated
Last updated
Общее описание
Ответ представляет собой объект с информацией о структуре динамической формы и данными форм для заполнения. Каждая форма размещена в соответствующем разделе (section
), который может содержать несколько форм (forms
), каждая из которых, в свою очередь, состоит из полей (fields
).
В общем виде структура форм выглядит следующим образом:
Структура может как состоять из 1 секции с 1 формой, так и из 10 секкциий по 5 форм, этим полностью управляет клиент
Отображение происходит от первой секции к третьей, по одной за запрос (после каждой секции вызывается хук динамических форм для сохранения введенных значений и получения следующей секции)
В самом начале, для получения первой секции в приложении, бекенд клиента будет получать следующее:
Описание полей
formId
- id формы которое было указано при добавлении формы в админке. строка, представляющая уникальный идентификатор формы, с которой производится действие. Пример: "form_2_1728392242894"
.
command
- команда, которая определяет действие, которое нужно выполнить. В данном случае это "start"
, что означает начало процесса работы с формой.
При заполнении секции будет выполнен еще 1 запрос для отправки введенных значений в бекенд клиента и получения либо следующей секции, либо сообщения о том что форма заполнена, который будет выглядеть следующим образом:
applicationId
- Используется для идентификации конкретной формы, с которой пользователь работает. Пример: "form_2_1728392242894"
. ВАЖНО! для запроса второй и дальше секции, будет использоваться это поле, а не formId
из начала заполнения
sectionId
: уникальный идентификатор секции, к которой относятся передаваемые значения. Пример: "section_1"
.
values
: объект, содержащий данные, которые ввел пользователь. Этот объект включает значения всех полей, указанных в секции. В качестве ключей используется id
поля
Пример формы из 1 секции с 2 элементами в forms
Пример ответа
applicationId
: идентификатор заявки, передается динамически в теле запроса.
status
: строка, отображающая текущий статус процесса обработки. Пример: "next"
.
data
: объект, содержащий информацию о разделах формы, их статусе, полях и действиях. Внутри этого объекта содержатся ключевые поля, такие как:
sections
: массив разделов, в которых каждый объект представляет отдельный раздел формы с информацией о его статусе, идентификаторе и полях.
sections
Каждый элемент массива sections
представляет собой раздел, который содержит формы для заполнения:
status
: статус заполнения секции, например, "not_started"
. Также если секция уже заполнена, то значение будет "complete"
sectionId
: уникальный идентификатор раздела, который используется для его идентификации.
name
: название секции. Пример: "Секция 1"
.
description
: описание секции. Может быть пустым.
forms
: массив форм, содержащихся в разделе.
forms
Каждая форма внутри раздела описывается следующими параметрами:
id
: уникальный идентификатор формы.
name
: название формы, например, "Личные данные"
.
description
: описание формы, например, "Описание формы"
.
values
: объект со значениями, если форма уже была частично заполнена. Например:
fields
: массив полей, содержащихся в форме. Описывается детально в следующем разделе.
fields
Каждое поле в массиве fields
включает следующие атрибуты:
type
: тип поля (например, "string"
, "boolean"
, "number"
, "select"
, "title"
, "credit-calculator"
и другие. смотри ниже структура всех существующих полей). Пример: "string"
.
id
: уникальный идентификатор поля. Пример: "name"
.
behaviour
: объект, определяющий поведение поля, включая такие атрибуты, как:
title
: заголовок поля. Пример: "Имя"
.
defaultValue
: значение по умолчанию. Пример: "Олег"
.
hidden
: флаг скрытия поля. Поле будет скрыто от пользователя, но учтено в условиях и запросах
Другие параметры, определяющие отображение и взаимодействие с полем (зависят от типа поля, поэтому будут описаны отдельно для каждого поля).
condition
: объект, определяющий условия отображения поля в зависимости от других полей.
Условия отображения полей
В некоторых случаях необходимо управлять видимостью определенных полей, секций или форм в зависимости от значений других полей. Для реализации данной функциональности в свойствах компонента следует использовать вложенные свойства condition
, такие как visible
или invisible
.
☝ Обратите внимание, что использование одновременно свойств
visible
иinvisible
не поддерживается. Необходимо выбирать только одно из этих свойств.
visible: Условие или массив условий, определяющих, при каких обстоятельствах поле должно отображаться.
invisible: Условие или массив условий, определяющих, при каких обстоятельствах поле должно быть скрыто.
Тип TConditionRules
Тип TConditionRules
представляет собой структуру, которая описывает правила условий для проверки видимости полей:
field: Идентификатор поля, значение которого необходимо проверить.
compare: Тип сравнения, который может принимать следующие значения:
eq: Проверяет, равно ли значение проверяемого поля заданному значению.
lt: Проверяет, меньше ли значение проверяемого поля заданного значения (применимо только для полей типа number
и date
).
gt: Проверяет, больше ли значение проверяемого поля заданного значения (применимо только для полей типа number
и date
).
filled: Проверяет, имеет ли проверяемое поле любое значение.
oneOf: Проверяет, является ли значение проверяемого поля одним из перечисленных вариантов.
value: Значение для сравнения, которое может быть как единичным, так и массивом значений для использования с типом oneOf
.
Пример
В данном примере, поле для которого будет указан данный condition, появится только в случае если будет отмечен поле-чекбокс с id agreement
validation
: объект, содержащий правила валидации поля, такие как required
(обязательно или нет), min
и max
значения, регулярные выражения для проверки, и другие параметры.
action
Каждая форма может содержать объект action
, который описывает кнопку подтверждения на форме (нужна либо для перехода к следующей форме раздела, либо к следующему разделу:
isAuto
: флаг автоматического выполнения действия. Пример: false
. Если true после заполнения всех полей формы, автоматически выполнится переход к следующей части
title
: заголовок кнопки действия. Пример: "Далее"
.
applicationId: Уникальный идентификатор заявки, который позволяет отслеживать заполненные формы.
status: Статус операции; в данном случае указывает на успешное завершение процесса.
title: Заголовок уведомления о результате; должен быть четким и кратким.
text: Сообщение для пользователя, благодарящее его за заполнение формы.
type
- string
id
- id поля (желательно, чтобы id всех полей были уникальные)
behaviour
- задает правила отображения поля
title
- заголовок поля, который будет отображаться пользователю, поясняя, что здесь необходимо указать стоимость.
defaultValue
- значение по умолчанию, заданное полю
hidden
: false
- определяет, будет ли поле видно пользователю. В данном случае false
, значит поле будет отображаться. Если бы стояло true
, то поле было бы скрыто.
disabled
: false
- указывает, можно ли редактировать поле. Здесь оно активно (то есть, false
), и пользователь может вводить данные. Если бы стояло true
, то поле было бы видно, но заблокировано для изменений.
uom
- единица измерения или подобное. Эта информация будет добавлена рядом с полем для пояснения.
Может отображаться в 2 вариантах
поле для в ввода
поле для ввода со слайдером
type
: "number"
— указывает на то, что это поле предназначено для ввода числового значения.
id
: "cost"
— уникальный идентификатор поля.
behaviour
: — объект, который определяет поведение и внешний вид поля. Включает следующие параметры:
title
: строка, задающая название поля, которое будет отображаться пользователю.
defaultValue
: значение по умолчанию. Может отсутствовать или быть заданным заранее.
numberView
: “slider” или “text” формат отображения поля. В данном случае оно выглядит как текстовое поле, хотя поддерживает ввод числовых данных.
hidden
: логическое значение, указывающее, будет ли поле скрытым на пользовательском интерфейсе. Если значение false
, поле отображается.
disabled
: логическое значение, указывающее, доступно ли поле для ввода. Если false
, поле активно и его можно редактировать.
uom
: строка, задающая единицу измерения, которая отображается рядом с полем. Она помогает пользователю понять, в каких единицах нужно вводить значение.
step
: числовое значение, указывающее шаг изменения значения в поле. Это определяет интервал между возможными вводимыми значениями. только для типа numberView
: “slider”
withoutPercent
: true/false, отключает вывод процентов для для типа numberView
: “slider”
validation: — объект, который описывает правила валидации для ввода данных:
required
: логическое значение, указывающее, является ли поле обязательным для заполнения. Если true
, пользователь должен ввести значение.
min
: числовое значение, задающее минимальное допустимое значение для этого поля. (обязательно для numberView
: “slider”)
max
: числовое значение, задающее максимальное допустимое значение для этого поля. (обязательно для numberView
: “slider”)
regex
: регулярное выражение, которое можно использовать для дополнительной проверки введённого значения.
type
: "title"
— указывает на то, что это поле является заголовком или текстовым блоком для отображения информации, а не для ввода данных.
id
: "text"
— уникальный идентификатор поля, который может быть использован для обращения к этому элементу на форме.
behaviour
: — объект, определяющий поведение и внешний вид поля. Включает следующие параметры:
title
: строка, представляющая текст, который будет отображаться пользователю. Это текстовое поле служит для описания чего-либо на форме, не предполагает ввода данных. Поле поддерживает форматирование Markdown, что позволяет добавлять ссылки или другие элементы форматирования текста.
size
: размер текста поля, может быть одним из следующих "xs" | "x" | "s" | "ms" | "m" | "ml" | "l" | "xl". по умолчанию "m"
Общее назначение:
Оба поля служат для получения согласия от пользователя. Первое поле отображается в виде кнопок для выбора между двумя опциями, а второе — в виде чекбокса. Оба поля могут быть использованы для различных юридических или пользовательских соглашений, а второе поле также поддерживает Markdown для добавления ссылок или пояснений.
Может быть в виде кнопок
type
: "boolean"
— указывает, что это поле принимает только два значения: true
(да) или false
(нет).
id
: "agreement"
— уникальный идентификатор поля, используемый для обращения к нему на форме.
behaviour
:
title
: строка, описывающая назначение поля. В данном случае, поле предназначено для получения согласия пользователя и отображается в виде кнопок.
defaultValue
: false
— значение по умолчанию для поля. Поле будет указывать на "нет" при первом отображении.
size
: "m"
— размер визуального элемента. В данном случае, используется средний размер.
booleanView
: "button"
— указывает на то, что визуальное представление поля будет реализовано в виде кнопок (например, "ДА" и "НЕТ").
booleanTrueText
: "ДА"
— текст, который будет отображаться для значения true
.
booleanFalseText
: "нет"
— текст, который будет отображаться для значения false
.
hidden
: false
— поле будет отображаться на форме, так как оно не скрыто.
Может быть в виде чекбокса
type
: "boolean"
— аналогично первому полю, это поле принимает только два значения: true
или false
.
id
: "agreement2"
— уникальный идентификатор этого поля.
behaviour
:
title
: строка, описывающая назначение поля. В данном случае, поле используется для получения согласия пользователя и отображается в виде чекбокса. Поддерживает форматирование Markdown для добавления ссылок или дополнительной информации.
defaultValue
: false
— значение по умолчанию, указывающее на "нет".
size
: "m"
— размер визуального элемента.
booleanView
: "checkbox"
— указывает, что визуальное представление поля будет реализовано в виде чекбокса.
hidden
: false
— поле будет отображаться на форме.
Может быть 1 из 3 вариантов. кнопки, выпадающий список, радиокнопки
type
: "select"
— указывает, что это поле позволяет выбрать один из предложенных вариантов.
id
: "select1"
— уникальный идентификатор поля, используемый для обращения к нему.
behaviour
:
title
: строка, описывающая назначение поля. В данном случае, поле предназначено для выбора одной из предустановленных опций.
hidden
: false
— поле будет отображаться на форме.
defaultValue
: "1"
— значение по умолчанию, устанавливающее первую опцию ("Студент") при первом отображении.
selectView
: "button"
— визуальное представление поля будет реализовано в виде кнопок, позволяющих быстро выбирать одну из опций. (может быть 1 из 3 вариантов “button”, “radio”, “dropdown”)
options
: массив объектов, представляющих доступные варианты:
label
: текст, который будет отображаться для пользователя.
value
: внутреннее значение, которое будет использоваться в логике приложения.
"Студент" (value: "1")
"Рабочий" (value: "2")
"Другое" (value: "3")
сейчас поддерживает маску только для рф номеров, для не рф используйте тип string
type
: "phone"
Указывает, что это поле предназначено для ввода телефонного номера. Специальные форматы и валидация могут быть применены для проверки корректности ввода.
id
: "phone"
Уникальный идентификатор поля, используемый для обращения к нему в коде или в логике приложения.
behaviour
:
title
: строка, описывающая назначение поля. В данном случае поле предназначено для ввода телефонного номера.
defaultValue
: null
— значение по умолчанию не установлено, поле будет пустым при первом отображении.
hidden
: false
— поле будет отображаться на форме, доступно для пользователя.
disabled
: false
— поле активно и доступно для редактирования пользователем.
type
: "date"
Указывает, что это поле предназначено для выбора даты. Обычно отображается в виде календаря, что облегчает выбор даты пользователем.
id
: "date"
Уникальный идентификатор поля, используемый для обращения к нему в коде или в логике приложения.
behaviour
:
title
: строка, описывающая назначение поля. Это поле предназначено для ввода даты.
defaultValue
: "2024-10-16"
— значение по умолчанию установлено на 16 октября 2024 года. Это значение будет отображаться при первом открытии формы.
hidden
: false
— поле будет отображаться на форме, доступно для пользователя.
disabled
: false
— поле активно и доступно для редактирования пользователем.
validation
: особые правила валидации для допустимых дат, остальное без отличий
min
: "2024-10-14"
— минимально допустимая дата, которую пользователь может выбрать. В данном случае это 14 октября 2024 года. Значения ниже этой даты не будут приняты.
max
: "2024-12-21"
— максимально допустимая дата, которую пользователь может выбрать. В данном случае это 21 декабря 2024 года. Значения выше этой даты не будут приняты.
type: "address"
Указывает, что это поле предназначено для ввода адреса. Обычно включает несколько компонентов, таких как улица, город, почтовый индекс и т. д.
id: "address"
Уникальный идентификатор поля, используемый для обращения к нему в коде или в логике приложения.
behaviour:
title: строка, описывающая назначение поля. Это поле предназначено для ввода адреса.
hidden: false
— поле будет отображаться на форме и доступно для пользователя.
Представляет из себя инпут, при нажатии на который, открывается модальное окно с картой и точками на ней
type: "pickup-place"
Указывает, что это поле предназначено для выбора точки на карте.
id: "ID"
Уникальный идентификатор поля, используемый для обращения к нему в коде или в логике приложения.
behaviour:
title: строка, описывающая назначение поля. Это поле предназначено для ввода адреса.
hidden: false
— поле будет отображаться на форме и доступно для пользователя.
mapOptions - обязательное
, для этого типа. массив
точек из который нужно выбрать.
id - string
, id точки, будет использован в качестве значения поля в заполненной форме, обязательное
поле
address - string
, ****адрес точки, обязательное
поле
lat - number
, широта. обязательное
поле
lon - number
, долгота. обязательное
поле
city - string
, город, необязательное
поле
line1 - string
, доп информация 1, например время работы , необязательное
поле
line2 - string
, доп информация 2, например график работы, необязательное
поле
subway - string
, название ближайшей станции метро, необязательное
поле
Общее назначение:
Поле предназначено для обеспечения навигации в рамках формы или интерфейса, позволяя пользователю быстро возвращаться к ранее заполненным секциям. Это полезно для улучшения пользовательского опыта, упрощая процесс заполнения и редактирования данных.
type: "nav-to-section"
Указывает, что это поле предназначено для навигации, позволяя пользователю вернуться к предыдущей секции формы или интерфейса.
id: "navToSection"
Уникальный идентификатор поля, используемый для обращения к нему в коде или в логике приложения.
behaviour:
title: строка, описывающая назначение поля. В данном случае — "Вернуться к предыдущей секции", что дает пользователю понять, что это действие позволит вернуться к ранее заполненной части формы.
hidden: false
— поле будет отображаться на форме и доступно для пользователя.
navId: строка "1"
— идентификатор секции, к которой будет происходить навигация. Это позволяет связать кнопку с конкретной частью интерфейса.
type: "file"
Указывает, что данное поле предназначено для загрузки файлов, таких как изображения или документы.
id: "file"
Уникальный идентификатор поля, который позволяет ссылаться на него в коде или логике приложения.
behaviour:
title: строка, описывающая назначение поля. В данном случае — "Фото товара или какой-то документ о владении". Это помогает пользователю понять, какой именно файл следует загрузить.
fileType: "image"
****тип загружаемого файла (default | image | document)
. По умолчанию default
(и фото и пдф)
Работает с хуком Хук отправки файлов в динамических формах V2
Конструктор форм imshop поддерживает вложенные формы, как один из типов полей. Вложенная форма имеет тот же функционал что и верхнеуровневая, нужна для добавления каких-то массивов одинаковых данных. Например описание нескольких товаров для оценки, описание водителей для страховки и подобное.
type
- form, тип поля
id
- id поля
behaviour
- объект, описание поля
isArray
- флаг того, что это должен быть массив с неограниченным числом форм
form
- объект формы, соответствующий верхнеуровнему объекту из массива sections.forms
action
- кнопка, для добавления следующего элемента в массиве и его полей