入力検証

スキーマのバージョン 1.3 以降、AdaptiveCards ではクライアント側での入力の種類の入力検証がサポートされています。

検証プロパティ

AdaptiveCards での検証では、次のプロパティがサポートされています。

入力	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 プロパティは、ユーザーが無効な値を入力した場合に表示する必要のあるエラーを指定するために、すべての入力の種類で使用できます。

注意

一部のプラットフォームでは、最小および最大のプロパティ (maxLength を含む) がコントロールによって直接適用される場合があります。 たとえば、日付選択で最小値よりも前の日付をユーザーが選択できないようにすることで、Input.Date の最小プロパティを適用できます。 その場合、エラー メッセージが表示されないことがあります。

ラベル

スキーマ バージョン 1.3 ですべての入力要素に対して追加されたもう 1 つのプロパティは、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" 値を使用するポップアップ表示カードを使ったホストの入力検証の動作は、適切に定義されていません。 ポップアップ表示カードは、今後のリリースで非推奨とされる場合があります。