入力検証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 PropertiesProperties
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.

注意

一部のプラットフォームでは、最小および最大のプロパティ (maxLength を含む) がコントロールによって直接適用される場合があります。Min and max properties (including maxLength) on some platforms may be enforced directly by the control. たとえば、日付選択で最小値よりも前の日付をユーザーが選択できないようにすることで、Input.Date の最小プロパティを適用できます。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 ですべての入力要素に対して追加されたもう 1 つのプロパティは、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 labelling 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.