Compartilhar via

Validação da entrada

  • Artigo

Nas versões 1.3 e posteriores do esquema, os Cartões Adaptáveis são compatíveis com a validação de tipos de entrada no lado do cliente.

Propriedades de validação

Estas propriedades são compatíveis com a validação nos Cartões Adaptáveis:

Entrada Propriedades
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

Uma propriedade errorMessage está disponível em todos os tipos de entrada para especificar qual erro deve ser mostrado se o usuário inserir um valor inválido.

Observação

Em algumas plataformas, as propriedades min e max (incluindo maxLength) podem ser impostas diretamente pelo controle. Por exemplo, é possível impor uma propriedade min em Input.Date não permitindo que os usuários selecionem uma data anterior à mínima em um seletor de data. Nesse caso, a mensagem de erro pode não ser mostrada.

Rótulos

Outra propriedade adicionada na versão do esquema 1.3 para todos os elementos de entrada é a propriedade de cadeia de caracteres label. Usar a propriedade label é a maneira recomendada de marcar entradas em um Cartão Adaptável, em relação à propriedade placeholder. É uma forma simples e concisa de rotular entradas para autores de cartão e tem os seguintes benefícios:

  • Indicadores de validação: conforme mencionado acima, agora as entradas podem ser marcadas como obrigatórias; os rótulos das entradas obrigatórias terão um indicador visual ao lado. Esse indicador visual é definido no HostConfig e, por padrão, é renderizado como um asterisco *.
  • Acessibilidade: tendo uma conexão entre rótulos e entradas, as bibliotecas de renderizador podem definir as propriedades necessárias para permitir que os usuários que usam tecnologias adaptativas (leitores de tela) consigam interagir corretamente com entradas dentro de cartões adaptáveis.
    • Rótulos versus espaços reservados: como Katie Sherwin explica no artigo Placeholders in form fields are harmful (Espaços reservados em campos de formulário são prejudiciais), o uso de espaços reservados tem muitas consequências negativas, a saber, a sobrecarga da memória de curto prazo dos usuários, a dificuldade que os usuários têm de verificar as entradas deles antes do envio, o problema que os usuários têm para lê-las, porque geralmente o texto tem um contraste de cor insatisfatório com relação ao segundo plano ou porque os leitores de tela não leem o texto do espaço reservado, apenas para citar algumas.
    • TextBlock e RichTextBlock: embora o uso de outros elementos de cartão como rótulos possa parecer uma boa solução, isso apresenta o problema da impossibilidade de impor a proximidade entre entradas e rótulos; por outro lado, usando a propriedade label, podemos verificar se ambos os elementos visuais são renderizados ao lado uns dos outros, o que ajuda os usuários que precisam de lupas.

Campos a serem validados e enviados

As entradas serão validadas quando o usuário clicar em uma ação Action.Submit no cartão. As entradas que serão validadas e enviadas para uma determinada ação Action.Submit são:

  • Entradas no mesmo cartão que Action.Submit
  • Entradas em quaisquer cartões pai do cartão que contém a Action.Submit, caso haja um cartão em Action.ShowCard

Se essas entradas forem validadas, os valores em seus campos serão passados de volta para o cliente. Caso contrário, as mensagens de erro para as entradas inválidas serão mostradas, e o envio não ocorrerá.

Observação

As entradas não serão validadas ou enviadas se estiverem em um cartão filho ou irmão do cartão que contém Action.Submit. Isso inclui cartões de Action.ShowCards em ActionSets no corpo do respectivo cartão. Essa é uma alteração no comportamento de versões do renderizador anteriores a 2.0. Aplica-se a cartões de todas as versões de esquema, independentemente do uso das propriedades de validação de entrada.

Outras considerações e problemas conhecidos

  • Não é recomendável criar entradas com propriedades de validação que nem sempre podem ser visíveis devido à interação com Action.ToggleVisibility. As mensagens de erro e as indicações visuais de que a entrada é inválida não serão mostradas se a entrada não estiver visível no momento, o que pode causar confusão para os usuários sobre o motivo pelo qual o envio foi bloqueado.

  • O comportamento da validação de entrada para hosts que usam cartões de exibição pop-up utilizando o valor "actions":"showCard":"actionMode":"popup" na configuração do host não está bem definido. Os cartões de exibição pop-up podem ser preteridos em uma versão futura.