アダプティブ カード レンダラーの仕様Adaptive Card Renderer Specification

次の仕様では、任意の UI プラットフォームにアダプティブ カード レンダラーを実装する方法について説明します。The following specification describes how implement an Adaptive Card renderer on any UI platform.

重要

このコンテンツはまだ完成していません。This content is not finished yet. 時間をおいて再度ご確認ください。Check back shortly.

SDK のバージョン管理SDK Versioning

  1. SDK のメジャー バージョンとマイナー バージョンは、schema バージョンと一致している必要がありますThe SDK major and minor version SHOULD match the schema version.
  2. スキーマの変更がないレンダラーの更新には、パッチ/ビルドを使用する必要がありますPatch/build SHOULD be used for renderer updates that don't have schema changes.

JSON の解析Parsing JSON

エラー条件Error conditions

  1. パーサーは、対象が有効な JSON コンテンツであることを確認する必要がありますA parser MUST check that it's valid JSON content
  2. パーサーは、スキーマに対して検証する必要があります (必要なプロパティなど)A parser MUST validate against the schema (required properties, etc)
  3. 上記のエラーはホスト アプリに報告する必要があります (例外または同等のもの)The above errors MUST be reported to the host app (exception or equivalent)

不明な種類Unknown types

  1. 不明な "種類" が検出された場合は、結果から削除する必要がありますIf unknown "types" are encountered they MUST BE DROPPED from the result
  2. ペイロードの変更 (上記など) はすべて、警告としてホストアプリに報告する必要がありますAny alterations of the payload (like above) SHOULD be reported as warnings to the host app

不明なプロパティUnknown properties

  1. パーサーは、要素に追加のプロパティを含める必要がありますA parser MUST include additional properties on elements

その他の考慮事項Additional considerations

  1. プロパティ speak は、SSML マークアップを含むことができ、指定されたとおりにホスト アプリに返される必要がありますThe speak property may contain SSML markup and MUST be returned to the host app as-specified

ホスト構成の解析Parsing Host Config

  1. TODOTODO

バージョン管理Versioning

  1. レンダラーは、スキーマの特定のバージョンを実装する必要がありますA renderer MUST implement a particular version of the schema.
  2. AdaptiveCard コンストラクターは、現在のスキーマのバージョンに基づいて、version プロパティに既定値を指定する必要がありますThe AdaptiveCard constructor MUST give the version property a default value based on the current schema version
  3. レンダラーは、サポートされているバージョンよりも上の AdaptiveCardversion プロパティを検出した場合、代わりに fallbackText を返す必要がありますIf a renderer encounters a version property in the AdaptiveCard that is higher than the supported version, it MUST return the fallbackText instead.

レンダリングRendering

AdaptiveCard は、bodyactions で構成されます。An AdaptiveCard consists of a body and actions. body は、レンダラーが列挙して順番にレンダリングする CardElement のコレクションです。The body is a collection of CardElements that a renderer will enumerate and render in order.

  1. 各要素は、親の幅まで引き伸ばす必要があります (HTML の display: block を思い浮かべてください)。Each Element MUST stretch to the width of its parent (think display: block in HTML).
  2. レンダラー は、不明な要素の種類を無視し、残りのペイロードのレンダリングを続行する必要がありますA renderer MUST ignore unknown element types, and continue rendering the rest of the payload.

スペースと区切り記号Spacing and Separators

  1. 各要素の spacing プロパティは、 現在の要素とその前の要素との間のスペースの量に影響します。The spacing property on every element influences the amount of space between the CURRENT element and the one BEFORE it.
  2. スペースは、実際にその前に要素がある場合にのみ適用する必要がありますSpacing MUST ONLY apply when there actually is an element preceding it. (例: 配列の最初の項目には適用されません)(E.g., won't apply to the first item in an array)
  3. レンダラーは、現在の要素に適用されている列挙値の hostConfig スペースから、使用するスペースの量を検索する必要がありますA renderer MUST look up the amount of space to use from the hostConfig spacing for the enum value applied to the current element.
  4. 要素の separator 値が true の場合は、現在の要素とその前の要素の間に可視線を描画する必要がありますIf the element has a separator value of true, then a visible line MUST be drawn between the current element and the one before it.
  5. 区切り線は、container.style.default.foregroundColor を使用して描画する必要がありますThe separator line MUST be drawn using the container.style.default.foregroundColor.
  6. 区切り記号は、項目が配列内の最初の要素ではない場合にのみ、描画する必要がありますA separator MUST ONLY be drawn if the item IS NOT the first in the array.

Columns

  1. Column width は "auto"、"stretch"、または重み付け比率で解釈される必要がありますColumn width MUST be interpreted by "auto", "stretch" or a weighted ratio.

TextBlockTextBlock

  1. TextBlock は、wrap プロパティが true でない限り、1 行である必要がありますA TextBlock MUST take up a single line unless the wrap property is true.
  2. テキスト ブロックは、余分なテキストを省略記号 (...) でトリミングする必要がありますThe text block SHOULD trim any excess text with an ellipsis (...)

マークダウンMarkdown

  1. アダプティブ カードはマークダウンのサブセットを許可します。また、アダプティブ カードは TextBlock でサポートされている必要がありますAdaptive Cards allow for a subset of Markdown and SHOULD be supported in TextBlock.
  2. 詳細なマークダウンの要件に関するページを参照してくださいSee full markdown requirements

書式設定関数Formatting functions

  1. TextBlock は、すべてのレンダラーでサポートされている必要がある日付/時刻書式設定関数を許可します。TextBlock allows DATE/TIME formatting functions that MUST be supported on every renderer.

  2. すべてのエラーで、カード内の未加工の文字列を表示する必要がありますALL FAILURES MUST display the raw string in the card. わかりやすいメッセージは試行されていません。No friendly message attempted. (問題が発生したことを開発者にすぐに認識させることが目的です)(The goal being to make the developer immediately aware there is a problem)

  3. TODO:正規表現を含めるTODO: Include regex

イメージImages

  1. レンダラーは、すべての HTTP イメージがダウンロードされ、カードが "完全にレンダリング" されたことをホスト アプリが認識できるようにする必要がありますA renderer SHOULD allow host apps to know when all HTTP images have been downloaded and the card is "fully rendered"
  2. レンダラーは、HTTP イメージをダウンロードするときにホスト構成 maxImageSize パラメーターを検査する必要がありますA renderer MUST inspect the Host Config maxImageSize param when downloading HTTP images
  3. レンダラーは、.png および .jpeg をサポートする必要がありますA renderer MUST support .png and .jpeg
  4. レンダラーは、.gif イメージをサポートする必要がありますA renderer SHOULD support .gif images

ホスト構成Host Config

  • TODO:既定値は何にしますか?TODO: What should the defaults be? すべてがそれを共有する必要がありますか?Should they all share it? 共通の hostConfig. json ファイルをバイナリに埋め込む必要がありますか?Should we embed a common hostConfig.json file in the binaries?
  • TODO:解析のために HostConfig にもバージョン管理が必要と考えます。TODO: I think HostConfig needs to be versioned as well for parsing?

HostConfig は、アダプティブ カード レンダラーが UI を生成する方法を指定する共有構成オブジェクトです。HostConfig is a shared configuration object that specifies how an Adaptive Card Renderer generates UI.

これにより、プラットフォームに依存しないプロパティをさまざまなプラットフォームやデバイス上のレンダラー間で共有できます。This allows properties which are platform agnostic to be shared among renderers on different platforms and devices. また、ツールを作成して、特定の環境に対してカードが持つルック アンド フィールを把握することもできます。It also allows tooling to be created which gives you an idea of the look and feel that card would have for a given environment.

  1. レンダラーは、ホスト アプリにホスト構成パラメーターを公開する必要がありますRenderers MUST expose a Host Config parameter to host apps
  2. すべての要素は、それぞれのホスト構成設定に従ってスタイル設定する必要がありますAll elements MUST be styled according to their respective Host Config settings

ネイティブ プラットフォームのスタイル設定Native platform styling

  1. 各要素の種類では、生成された UI 要素と共にネイティブ プラットフォーム スタイルを付加する必要がありますEach element type SHOULD attach a native platform style with the generated UI element. 例: HTML では要素の種類に CSS クラスを追加し、XAML では特定のスタイルを割り当てる。E.g., in HTML we added a CSS class to the element types, and in XAML we assign a specific Style.

拡張性Extensibility

  1. レンダラーは、ホスト アプリが既定の要素レンダラーをオーバーライドできるようにする必要がありますA renderer MUST allow host apps to override default element renderers. 例: TextBlock レンダリングを独自のロジックに置き換える。E.g., replace TextBlock rendering with their own logic.
  2. レンダラーは 、ホスト アプリがカスタム要素の種類を登録できるようにする必要がありますA renderer MUST allow host apps to register custom element types. 例: カスタム Rating 要素のサポートを追加するE.g., add support for a custom Rating element
  3. レンダラーは、ホスト アプリが既定の要素のサポートを削除できるようにする必要がありますA renderer MUST allow host apps to remove support for a default element. 例: Action.Submit をサポートしたくない場合にそれを削除する。E.g., remove Action.Submit if they don't want it supported.

操作Actions

  1. HostConfig supportsInteractivityfalse の場合、レンダラーは何のアクションもレンダリングしてはなりませんIf HostConfig supportsInteractivity is false, a renderer MUST NOT render any actions.
  2. actions プロパティは、何らかの種類のアクション バー (通常はカードの下部) のボタンとしてレンダリングされる必要がありますThe actions property MUST be rendered as buttons in some kind of action bar, usually at the bottom of the card.
  3. ボタンがタップされたときに、ホスト アプリでイベントを処理できるようにする必要がありますWhen a button is tapped it MUST allow the host app to handle the event.
  4. イベントは、アクションに関連するすべてのプロパティを渡す必要がありますThe event MUST pass along all associated properties with the action
  5. イベントは、実行された AdaptiveCard と共に渡す必要がありますThe event MUST pass along the AdaptiveCard which was executed
操作Action 動作Behavior
Action.OpenUrlAction.OpenUrl 表示用に外部 URL を開きますOpen an external URL for viewing
Action.ShowCardAction.ShowCard ユーザーに表示するサブカードを要求します。Requests a sub-card to be shown to the user.
Action.SubmitAction.Submit すべての入力要素を 1 つのオブジェクトにまとめ、ホスト アプリケーションによって定義された何らかの方法でユーザーに送信するように要求します。Ask for all of the input elements to be gathered up into an object which is then sent to you through some method defined by the host application.

Action.OpenUrlAction.OpenUrl

  1. Action.OpenUrl では、ネイティブ プラットフォーム メカニズムを使用して URL を開く必要がありますAction.OpenUrl SHOULD open a URL using the native platform mechanism
  2. これができない場合は、URL を開くことを処理するために、ホスト アプリにイベントを発生させる必要がありますIf this is not possible it MUST raise an event to the host app to handle opening the URL. このイベントは、ホスト アプリが既定の動作をオーバーライドできるようにする必要がありますThis event MUST allow the host app to override the default behavior. 例: 独自のアプリ内で URL を開けるようにする。E.g., let them open the URL within their own app.

Action.ShowCardAction.ShowCard

  1. Action.ShowCard は、hostConfig 設定に基づいて、何らかの方法でサポートされている必要がありますAction.ShowCard MUST be supported in some way, based on the hostConfig setting. インラインとポップアップの 2 つのモードがあります。There are two modes: inline, and popup. インライン カードでは、カードの可視性を自動的に切り替える必要がありますInline cards SHOULD toggle the card visibility automatically. ポップアップ モードでは、何らかの方法でカードを表示するために、ホスト アプリにイベントを発生させる必要がありますIn popup mode, an event SHOULD be fired to the host app to show the card in some way.

Action.SubmitAction.Submit

Submit アクションは HTML フォームの送信のように動作しますが、HTML が通常 HTTP POST をトリガーする場合、アダプティブ カードは "submit" がどのような意味を持つのかの判断を各ホスト アプリに委任する点が異なります。The Submit Action behaves like an HTML form submit, except that where HTML typically triggers an HTTP post, Adaptive Cards leaves it up to each host app to determine what "submit" means to them.

  1. これがイベントを発生させる必要がある場合は、呼び出されたアクションをユーザーがタップします。When this MUST raise an event the user taps the action invoked.
  2. data プロパティは、コールバック ペイロードに含まれている必要がありますThe data property MUST be included in the callback payload.
  3. Action.Submit では、レンダラーはカード上のすべての入力を収集し、それらの値を取得する必要がありますFor Action.Submit, a renderer MUST gather all inputs on the card and retrieve their values.

selectActionselectAction

  1. ホスト構成 supportedInteractivityfalse の場合、selectAction はタッチ ターゲットとしてレンダリングしてはなりませんIf Host Config supportedInteractivity is false then a selectAction MUST NOT render as a touch target.
  2. ImageColumnSet、および Column には selectAction プロパティが用意されています。これは、ユーザーが要素をタップするなどして呼び出したときに実行される必要がありますImage, ColumnSet, and Column offer a selectAction property, which SHOULD be executed when the user invokes it, e.g., by tapping the element.

入力Inputs

  1. HostConfig supportsInteractivityfalse の場合、レンダラーは何の入力もレンダリングしてはなりませんIf HostConfig supportsInteractivity is false a renderer MUST NOT render any inputs.

  2. 入力は、可能な限り高い忠実度でレンダリングする必要がありますInputs SHOULD render with the highest fidelity possible. たとえば、Input.Date では、ユーザーに日付の選択コントロールを提供するのが理想的ですが、UI スタックでこれができない場合、レンダラーは標準のテキスト ボックスのレンダリングにフォールバックする必要がありますFor example, an Input.Date would ideally offer a date picker to a user, but if this isn't possible on your UI stack, then the renderer MUST fall back to rendering a standard text box.

  3. 可能な場合、レンダラーは placeholderText を表示する必要がありますA renderer SHOULD display the placeholderText if possible

  4. レンダラーは、入力の検証を実装する必要はありませんA renderer DOES NOT have to implement validation of the input. アダプティブ カードのユーザーは、受信したデータを各自で検証するように計画する必要があります。Users of Adaptive Cards must plan to validate any received data on their end.

  5. 入力値のバインドを適切にエスケープする必要がありますInput value binding MUST be properly escaped

  6. オブジェクトは、次のようにホスト アプリに返される必要がありますThe object MUST be returned to the host app as follows:

    アダプティブ カードでは入力の検証の保証はないため、応答を適切に解析することは受信側の責任になります。We do not make any promises of input validation in adaptive cards, so it's up to the receiving party to properly parse the response. 例: Input.Number で "hello" が返される可能性があり、そのための準備が必要になる。E.g., a Input.Number could return "hello" and they need to be prepared for that.

[イベント]Events

  1. レンダラーは、要素の可視性が変更されたときにイベントを発生させる必要があります。これにより、ホスト アプリはカードを所定の位置にスクロールできます。A renderer SHOULD fire an event when an element's visibility has changed, allowing the host app to scroll the card into position.