입력 유효성 검사

  • 아티클

버전 1.3 이상의 스키마에서 AdaptiveCards는 입력 형식에 대한 클라이언트 측 입력 유효성 검사를 지원합니다.

유효성 검사 속성

AdaptiveCards의 유효성 검사에 지원되는 속성은 다음과 같습니다.

입력 속성
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 포함)은 컨트롤을 통해 직접 적용할 수 있습니다. 예를 들어, Input.Date의 min 속성은 사용자가 날짜 선택기에서 최솟값 이전의 날짜를 선택하지 못하도록 적용할 수 있습니다. 이 경우 오류 메시지가 표시되지 않을 수 있습니다.

레이블

스키마 버전 1.3에서 모든 입력 요소에 추가된 또 다른 속성은 label 문자열 속성입니다. 적응형 카드에서 입력에 태그를 지정할 때는 placeholder 속성보다 label 속성을 사용하는 것이 좋습니다. 카드 작성자는 이를 통해 입력 레이블을 간결하고 명료하게 지정할 수 있으며 다음과 같은 이점이 있습니다.

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

유효성을 검사하고 제출할 필드

사용자가 카드에서 Action.Submit 작업을 클릭하면 입력의 유효성이 검사됩니다. 주어진 Action.Submit 작업에 대해 유효성을 검사하고 제출할 입력은 다음과 같습니다.

  • Action.Submit과 동일한 카드의 입력
  • Action.ShowCard 아래에 있는 카드의 경우 Action.Submit을 포함하는 카드의 부모 카드에 대한 입력

해당 입력이 유효성 검사를 통과하면 해당 필드의 값이 클라이언트에 다시 전달됩니다. 유효성 검사를 통과하지 못하면 잘못된 입력에 대한 오류 메시지가 표시되고 제출이 전송되지 않습니다.

참고

입력이 Action.Submit을 포함하는 카드의 자식 또는 형제 카드에 있는 경우 입력의 유효성이 검사되거나 제출되지 않습니다. 여기에는 해당 카드 본문의 ActionSets에 있는 Action.ShowCards의 카드가 포함됩니다. 2\.0 이전의 렌더러 버전에서 변경된 동작이며, 입력 유효성 검사 속성이 사용되는지 여부에 관계없이 모든 스키마 버전의 카드에 적용됩니다.

기타 고려 사항 및 알려진 문제

  • Action.ToggleVisibility와의 상호 작용으로 인해 항상 표시되지 않을 수 있는 유효성 검사 속성을 사용하여 입력을 만드는 것은 권장되지 않습니다. 입력이 현재 보이지 않으면 입력이 유효하지 않다는 오류 메시지와 시각적 표시가 표시되지 않으므로 제출이 차단된 이유에 대해 사용자에게 혼동을 줄 수 있습니다.

  • 호스트 구성에서 "actions":"showCard":"actionMode":"popup" 값을 사용하는 팝업 표시 카드를 사용하는 호스트에 대한 입력 유효성 검사 동작이 제대로 정의되어 있지 않습니다. 이후 릴리스에서는 팝업 표시 카드가 더 이상 사용되지 않을 수 있습니다.