입력 유효성 검사Input Validation

버전 1.3 이상의 스키마에서 AdaptiveCards는 입력 형식에 대한 클라이언트 측 입력 유효성 검사를 지원합니다.In versions 1.3 and later of the schema, AdaptiveCards supports client side input validation of Input types.

유효성 검사 속성Validation Properties

AdaptiveCards의 유효성 검사에 지원되는 속성은 다음과 같습니다.The following properties are supported for validation in AdaptiveCards:

입력Input 속성Properties
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 속성은 모든 입력 형식에서 사용할 수 있으며, 사용자가 잘못된 값을 입력하는 경우 표시되어야 하는 오류를 지정할 수 있습니다.An errorMessage property is available on all input types to specify what error a user should be shown if they enter an invalid value.

참고

일부 플랫폼의 min 및 max 속성(maxLength 포함)은 컨트롤을 통해 직접 적용할 수 있습니다.Min and max properties (including maxLength) on some platforms may be enforced directly by the control. 예를 들어, Input.Date의 min 속성은 사용자가 날짜 선택기에서 최솟값 이전의 날짜를 선택하지 못하도록 적용할 수 있습니다.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. 이 경우 오류 메시지가 표시되지 않을 수 있습니다.In that case, the error message may not be shown.

레이블Labels

스키마 버전 1.3에서 모든 입력 요소에 추가된 또 다른 속성은 label 문자열 속성입니다.Another property added in schema version 1.3 for all input elements is the label string property. 적응형 카드에서 입력에 태그를 지정할 때는 placeholder 속성보다 label 속성을 사용하는 것이 좋습니다.Using the label property is the recommended way of tagging inputs in an Adaptive Card, vis-a-vis the placeholder property. 카드 작성자는 이를 통해 입력 레이블을 간결하고 명료하게 지정할 수 있으며 다음과 같은 이점이 있습니다.It is a simple and concise way of labeling inputs for card authors and has the following benefits:

  • 유효성 검사 표시기: 위에서 언급한 것처럼, 이제 입력이 필수로 표시될 수 있습니다. 필수 입력 레이블 옆에 시각적 표시기가 있을 것입니다.Validation indicators: as mentioned above inputs can be now marked as required, labels for required inputs will have a visual indicator next to them. 이 시각적 표시기는 HostConfig에 정의되며 기본적으로 별표(*)로 렌더링됩니다.This visual indicator is defined in the HostConfig and by default is rendered as an asterisk *.
  • 접근성: 렌더러 라이브러리는 레이블과 입력을 연결하여 보조 기술(화면 판독기) 사용자가 적응형 카드 내의 입력과 올바르게 상호 작용할 수 있도록 하는 데 필요한 속성을 설정할 수 있습니다.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.
    • 레이블과 자리 표시자: Katie Sherwin이 Placeholders in form fields are harmful 문서에서 설명한 것처럼, 자리 표시자를 사용하면 여러 가지 부정적인 결과가 나타납니다. 예를 들어 사용자의 단기 메모리 부담 가중, 사용자가 입력을 제출하기 전에 확인하기 어려움, 사용자의 가독성 저해, 자리 표시자 텍스트와 배경색의 불분명한 색상 대비, 화면 판독기가 자리 표시자 텍스트를 전혀 판독하지 않는 등의 단점이 있습니다.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 및 RichTextBlock: 다른 카드 요소를 레이블로 사용하는 방법은 좋은 해결책으로 보일 수 있지만 입력과 레이블 사이에 근접성을 적용할 수 없다는 문제가 있습니다. 반면에 label 속성을 사용하면 두 시각적 요소가 서로 나란히 렌더링되므로 화면 돋보기가 필요한 사용자에게 유용합니다.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.

유효성을 검사하고 제출할 필드Fields to be validated and submitted

사용자가 카드에서 Action.Submit 작업을 클릭하면 입력의 유효성이 검사됩니다.Inputs will be validated when the user clicks on an Action.Submit action in the card. 주어진 Action.Submit 작업에 대해 유효성을 검사하고 제출할 입력은 다음과 같습니다.Those inputs which will be validated and submitted for a given Action.Submit action are:

  • Action.Submit과 동일한 카드의 입력Inputs on the same card as the Action.Submit
  • Action.ShowCard 아래에 있는 카드의 경우 Action.Submit을 포함하는 카드의 부모 카드에 대한 입력Inputs on any parent cards of the card containing the Action.Submit in the case of a card under an Action.ShowCard

해당 입력이 유효성 검사를 통과하면 해당 필드의 값이 클라이언트에 다시 전달됩니다.If those inputs pass validation, the values in their fields will be passed back to the client. 유효성 검사를 통과하지 못하면 잘못된 입력에 대한 오류 메시지가 표시되고 제출이 전송되지 않습니다.If they do not pass validation, the error messages for the invalid inputs will be shown, and the submit will not be sent.

참고

입력이 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. 여기에는 해당 카드 본문의 ActionSets에 있는 Action.ShowCards의 카드가 포함됩니다.This includes cards from Action.ShowCards in ActionSets in the body of that card. 2.0 이전의 렌더러 버전에서 변경된 동작이며, 입력 유효성 검사 속성이 사용되는지 여부에 관계없이 모든 스키마 버전의 카드에 적용됩니다.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.

기타 고려 사항 및 알려진 문제Other Considerations and Known Issues

  • Action.ToggleVisibility와의 상호 작용으로 인해 항상 표시되지 않을 수 있는 유효성 검사 속성을 사용하여 입력을 만드는 것은 권장되지 않습니다.It is not recommended to create inputs with validation properties that may not always be visible due to interaction with Action.ToggleVisibility. 입력이 현재 보이지 않으면 입력이 유효하지 않다는 오류 메시지와 시각적 표시가 표시되지 않으므로 제출이 차단된 이유에 대해 사용자에게 혼동을 줄 수 있습니다.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.

  • 호스트 구성에서 "actions":"showCard":"actionMode":"popup" 값을 사용하는 팝업 표시 카드를 사용하는 호스트에 대한 입력 유효성 검사 동작이 제대로 정의되어 있지 않습니다.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. 이후 릴리스에서는 팝업 표시 카드가 더 이상 사용되지 않을 수 있습니다.Popup show cards may be deprecated in a future release.