Поделиться через

Проверка входных данных

  • Статья

В версии схемы 1.3 и более поздних версиях адаптивные карточки поддерживают проверку входных данных типов Input на стороне клиента.

Свойства проверки

Адаптивные карточки поддерживают следующие свойства для проверки:

Входные данные Свойства
Input.ChoiceSet isRequired
Input.Date isRequired
min
max
Input.Number isRequired
min
max
Input.Text isRequired
regex
maxLength
Input.Time isRequired
min
max
Input.Toggle isRequired

Свойство errorMessage доступно для входных данных всех типов. Оно позволяет указать, какое сообщение об ошибке должно отобразиться для пользователя, если он вводит недопустимое значение.

Примечание

Свойства min и max (включая maxLength) на некоторых платформах могут принудительно применяться непосредственно элементом управления. Например, можно принудительно применить свойство min для Input.Date, запретив пользователям выбирать даты, предшествующие минимальному значению, в управляющем элементе выбора даты. В таком случае сообщение об ошибке может не отображаться.

Метки

В схеме версии 1.3 для всех входных элементов добавлено еще одно строковое свойство label. Свойство label рекомендуется использовать для добавления тегов к входным данным в адаптивной карте вместо свойства placeholder. Так создатели карточек могут без усилий размечать входные данные, получая следующие преимущества:

  • Индикаторы проверки. Как упоминалось выше, входные данные могут быть помечены как обязательные, и тогда метки для обязательных параметров будут иметь визуальный индикатор. Такой индикатор определяется в HostConfig, и по умолчанию для него используется звездочка *.
  • Специальные возможности. Благодаря связям между метками и входными данными библиотеки отрисовщика могут задавать необходимые свойства, позволяя пользователям применять вспомогательные технологии (например, средства чтения с экрана) для правильной работы с входными данными в адаптивных карточках.
    • Метки и заполнители. Кейти Шервин (Katie Sherwin) в своей статье объясняет, что использование заполнителей влечет множество негативных последствий, включая ограничение краткосрочной памяти для пользователей, усложнение проверки входных данных перед отправкой, затруднение чтения из-за того, что текст заполнителя обычно имеет низкую контрастность относительно фона, нарушение работы программ чтения с экрана и многое другое.
    • TextBlock и RichTextBlock. Использование других элементов карточки в качестве метки может показаться хорошим решением, но в этом случае входные данные и метки невозможно расположить рядом. С другой стороны, использование свойства label обеспечит отрисовку этих визуальных элементов рядом друг с другом, что очень полезно для тех пользователей, которые используют экранные лупы.

Поля для проверки и отправки

Входные данные будут проверены, когда пользователь щелкнет действие Action.Submit на карточке. Для определенного действия Action.Submit будут проверяться и отправляться следующие входные данные:

  • входные данные, содержащиеся в карточке, на которой выбрано действие Action.Submit;
  • входные данные во всех родительских карточках той карточки, на которой выбрано действие Action.Submit, при использовании Action.ShowCard.

Если эти входные данные проходят проверку, значения в их полях будут возвращены клиенту. Если данные не проходят проверку, для недопустимых входных данных отобразятся сообщения об ошибках и отправка не будет выполнена.

Примечание

Входные данные не будут проверяться или отправляться, если они содержатся в карточке, которая является дочерней или родственной для карточки, на которой выбрано действие Action.Submit. Сюда входят карточки, охватываемые Action.ShowCards в ActionSets в тексте карточки. Это изменение в поведении наблюдается, начиная с версии отрисовщика 2.0. Оно характерно для карточек со всеми версиями схемы, независимо от того, используются ли свойства проверки входных данных.

Другие рекомендации и известные проблемы

  • Не рекомендуем создавать входные данные со свойствами проверки, которые не всегда могут быть видимыми из-за взаимодействия с Action.ToggleVisibility. Сообщения об ошибках и визуальные индикаторы того, что входные данные недопустимы, не будут отображаться, если входные данные сейчас не видны. Это может вызвать замешательство у пользователей, которые не будут понимать, почему их отправка заблокирована.

  • Поведение при проверке входных данных для основных элементов, использующих всплывающее окно для отображения карточек (значение "actions":"showCard":"actionMode":"popup" в конфигурации), недостаточно хорошо определено. Возможно, в следующем выпуске всплывающее окно для отображения карточек будет отмечено как нерекомендуемое.