Validation d'entréeInput Validation

Dans les versions 1.3 et ultérieures du schéma, le format Cartes adaptatives prend en charge la validation des entrées côté client des types Entrée.In versions 1.3 and later of the schema, AdaptiveCards supports client side input validation of Input types.

Propriétés de validationValidation Properties

Les propriétés suivantes sont prises en charge pour la validation dans Cartes adaptatives :The following properties are supported for validation in AdaptiveCards:

EntréeInput PropriétésProperties
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

Une propriété errorMessage est disponible sur tous les types d’entrée afin de spécifier quelle erreur doit être affichée à l’utilisateur s’il saisit une valeur non valide.An errorMessage property is available on all input types to specify what error a user should be shown if they enter an invalid value.

Notes

Les propriétés min et max (y compris maxLength) de certaines plateformes peuvent être appliquées directement par le contrôle.Min and max properties (including maxLength) on some platforms may be enforced directly by the control. Par exemple, une propriété min sur Input.Date peut être appliquée ne permettant pas aux utilisateurs de sélectionner une date antérieure au minimum dans un sélecteur de dates.For example, a min property on Input.Date may be enforced by not allowing users to select a date before the minimum in a date picker. Dans ce cas, il est possible que le message d’erreur ne s’affiche pas.In that case, the error message may not be shown.

ÉtiquettesLabels

La propriété de chaîne label est une autre propriété ajoutée dans le schéma version 1.3 pour tous les éléments d’entrée.Another property added in schema version 1.3 for all input elements is the label string property. L’utilisation de la propriété label est la méthode recommandée pour étiqueter les entrées dans une carte adaptative, vis-à-vis de la propriété placeholder .Using the label property is the recommended way of tagging inputs in an Adaptive Card, vis-a-vis the placeholder property. Il s’agit d’un moyen simple et concis d’étiqueter les entrées pour les auteurs de cartes. Il présente les avantages suivants :It is a simple and concise way of labelling inputs for card authors and has the following benefits:

  • Indicateurs de validation : comme indiqué ci-dessus, les entrées peuvent maintenant être marquées comme obligatoires, les étiquettes pour les entrées obligatoires auront un indicateur visuel à côté.Validation indicators: as mentioned above inputs can be now marked as required, labels for required inputs will have a visual indicator next to them. Cet indicateur visuel est défini dans HostConfig et est rendu par défaut sous la forme d’un astérisque *.This visual indicator is defined in the HostConfig and by default is rendered as an asterisk *.
  • Accessibilité : avec une connexion entre les étiquettes et les entrées, les bibliothèques de renderers peuvent définir les propriétés nécessaires pour permettre aux utilisateurs qui se servent des technologies d’assistance (lecteurs d’écran) de pouvoir interagir correctement avec les entrées au sein des cartes adaptatives.Accessibility: by having a connection between labels and inputs, renderer libraries can set the necessary properties to allow users using assistive technologies (screen readers) to be able to interact correctly with inputs inside adaptive cards.
    • Étiquettes ou espaces réservés : comme Katie Sherwin l’explique dans l’article Placeholders in form fields are harmful, l’utilisation d’espaces réservés a de nombreuses conséquences négatives, telles que la sollicitation de la mémoire à court terme des utilisateurs (ce qui leur rend la tâche plus difficile pour vérifier leurs entrées avant de les soumettre), des difficultés à les lire car, généralement, le texte des espaces réservés présente un contraste de couleurs très faible par rapport à son arrière-plan, l’impossibilité totale pour les lecteurs d’écran de lire le texte des espaces réservés, pour n’en citer que quelques-unes.Labels vs Placeholders: as Katie Sherwin explains in the article Placeholders in form fields are harmful using placeholders has many negative consequences such as straining users' short term memory, making it harder for users to verify their inputs before submitting, providing difficulties for users to read them as, usually, placeholder text has poor color contrast against it's background or screen readers not reading the placeholder text at all, just to name a few.
    • TextBlock et RichTextBlock : alors que l’utilisation d’autres éléments de carte comme les étiquettes peut sembler être une bonne solution, elle présente le problème de ne pas pouvoir appliquer de proximité entre les entrées et les étiquettes. Par contre, en utilisant la propriété label, nous pouvons garantir que les deux éléments visuels sont rendus les uns à côté des autres, ce qui aide les utilisateurs qui ont besoin d’une loupe d’écran.TextBlock and RichTextBlock: while using other card elements as labels may seem as a good solution it presents the issue of not being able to enforce proximity between inputs and labels, on the other hand by using the label property, we can ensure that both visual elements are rendered next to each other which helps users who need screen magnifiers.

Champs à valider et à envoyerFields to be validated and submitted

Les entrées seront validées lorsque l’utilisateur cliquera sur une action Action.Submit dans la carte.Inputs will be validated when the user clicks on an Action.Submit action in the card. Les entrées qui seront validées et envoyées pour une action Action.Submit donnée sont les suivantes :Those inputs which will be validated and submitted for a given Action.Submit action are:

  • Entrées sur la même carte que l’action Action.SubmitInputs on the same card as the Action.Submit
  • Entrées sur toute carte parent de la carte contenant l’action Action.Submit dans le cas d’une carte sous une action Action.ShowCardInputs on any parent cards of the card containing the Action.Submit in the case of a card under an Action.ShowCard

Si ces entrées sont validées, les valeurs de leurs champs sont renvoyées au client.If those inputs pass validation, the values in their fields will be passed back to the client. Si elles ne sont pas validées, les messages d’erreur des entrées non valides s’affichent et la soumission n’est pas envoyée.If they do not pass validation, the error messages for the invalid inputs will be shown, and the submit will not be sent.

Notes

Les entrées ne seront pas validées ni envoyées si elles figurent sur une carte enfant ou frère de la carte contenant l’action Action.Submit.Inputs will not be validated or submitted if they are on a card that is a child or sibling card of the card containing the Action.Submit. Cela comprend les cartes d’Action.ShowCards dans ActionSets dans le corps de cette carte.This includes cards from Action.ShowCards in ActionSets in the body of that card. Il s’agit d’une modification du comportement par rapport aux versions de rendu antérieures à la version 2.0 qui s’applique aux cartes de toutes les versions de schéma, que les propriétés de validation d’entrée soient ou non utilisées.This is a change in behavior from renderer versions prior to 2.0, and applies to cards of all schema versions, regardless of whether input validation properties are used.

Autres considérations et problèmes connusOther Considerations and Known Issues

  • Il n’est pas recommandé de créer des entrées avec des propriétés de validation susceptibles de ne pas être toujours visibles en raison de l’interaction avec Action.ToggleVisibility.It is not recommended to create inputs with validation properties that may not always be visible due to interaction with Action.ToggleVisibility. Les messages d’erreur et les indications visuelles selon lesquelles l’entrée n’est pas valide ne s’afficheront pas si l’entrée n’est pas visible actuellement, ce qui peut entraîner une confusion pour les utilisateurs quant à la raison pour laquelle leur soumission est bloquée.Error messages and visual indications that the input is invalid will not be shown if the input is not currently visible, which may cause confusion for users as to why their submit is blocked.

  • Le comportement de la validation d’entrée pour les hôtes utilisant des cartes d’affichage contextuelles à l’aide de la valeur "actions":"showCard":"actionMode":"popup" dans leur configuration d’hôte n’est pas bien défini.Behavior of input validation for hosts using popup show cards using the "actions":"showCard":"actionMode":"popup" value in their host config is not well defined. Il est possible que les cartes d’affichage contextuelles soient déconseillées dans une prochaine version.Popup show cards may be deprecated in a future release.