入力検証

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

検証プロパティ

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

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

ラベル

スキーマ バージョン 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.ToggleVisibility との対話によって表示されないこともある検証プロパティを使用して入力を作成することはお勧めしません。 入力が現在表示されていない場合、入力が無効であることを示すエラー メッセージと視覚的な指示は表示されません。そのため、送信がブロックされる理由について、ユーザーに混乱が生じる可能性があります。

• ホスト構成内の "actions":"showCard":"actionMode":"popup" 値を使用するポップアップ表示カードを使ったホストの入力検証の動作は、適切に定義されていません。 ポップアップ表示カードは、今後のリリースで非推奨とされる場合があります。