Спецификация отрисовщика адаптивных карточек

Следующая спецификация описывает, как реализовать отрисовщик адаптивных карточек на любой встроенной платформе пользовательского интерфейса.

Важно!

Это содержимое считается незаконченным и в нем могут отсутствовать некоторые сведения. Если у вас есть комментарии или вопросы, сообщите нам об этом.

Анализ JSON

Условия ошибок

1. Анализатор должен проверять допустимость содержимого JSON.
2. Анализатор должен проверять схему (обязательные свойства и т. д.).
3. Сведения об указанных выше ошибках должны передаваться ведущему приложению (исключение или аналог).

Неизвестные типы

1. Если обнаружены неизвестные "типы", они должны быть удалены из полученного результата.
2. Любые изменения полезных данных (как показано выше) должны быть переданы в виде предупреждений в ведущее приложение.

Неизвестные свойства

1. Анализатор должен добавить дополнительные свойства элементов.

Дополнительные сведения

1. Свойство speakМОЖЕТ содержать разметку SSML и ДОЛЖНО возвращаться в ведущее приложение, как указано.

Анализ HostConfig

1. TODO

Управление версиями

1. Отрисовщик должен реализовывать определенную версию схемы.
2. Конструктор AdaptiveCardдолжен присвоить свойству version значение по умолчанию, основанное на текущей версии схемы.
3. Если отрисовщик обнаруживает свойство version в AdaptiveCard, значение которого больше номера текущей поддерживаемой версии, то он должен возвращать fallbackText.

Отрисовка

Объект AdaptiveCard состоит из элементов body и actions. Элемент body представляет собой коллекцию элементов CardElement, которые отрисовщик будет перечислять и отображать по порядку.

1. Каждый элемент должен быть растянут до ширины его родительского элемента (вспомните о display: block в HTML).
2. Отрисовщик ДОЛЖЕН игнорировать любые неизвестные типы элементов, которые он встретит, и продолжать отрисовку оставшейся части полезных данных.

Text, TextBlock и RichTextBlock

1. Элемент TextBlock должен занимать одну строку, если только свойство wrap не имеет значение true.
2. Текстовый блок должен обрезать любой лишний текст с помощью многоточия (…).

Markdown

1. Адаптивные карточки поддерживают часть элементов Markdown, которые должны поддерживаться в объектах TextBlock.
2. RichTextBlock НЕ ПОДДЕРЖИВАЕТ разметку Markdown, и его необходимо форматировать с использованием предоставляемых свойств.
3. Ознакомьтесь с полными требованиями к Markdown.

Функции форматирования

1. TextBlock допускает использование функций форматирования даты и времени, которые должны поддерживаться каждым отрисовщиком.
2. Все сообщения об ошибке должны отображать необработанную строку в карточке. Понятное сообщение о попытке отображать не нужно. (Это нужно для того, чтобы разработчик сразу узнал о проблеме.)

Изображения

1. Отрисовщик должен давать ведущим приложениям возможность определить, когда все изображения HTTP скачаны и карточка полностью отображена.
2. Отрисовщик должен проверять параметр maxImageSize HostConfig при скачивании изображений HTTP.
3. Отрисовщик должен поддерживать .png и .jpeg.
4. Отрисовщик должен поддерживать изображения с расширением .gif.

Поведение расширенного макета

Отрисовщик ДОЛЖЕН соблюдать следующие поведения при преобразовании для просмотра элементов карточки по отношению к атрибутам, упомянутым в этом документе.

Отрисовщик должен управлять ограничениями, принимая во внимание различные факторы конфигурации элементов карточки и ее дочерних элементов, таких как поля, отступы, высота и ширина и т. д.

Ширина

1. Допустимые значения — auto, stretch и фиксированные значения с точки зрения pixels и weight.
2. auto предоставляет достаточно места для расширения (поддерживает минимальное расширение).
3. stretch занимает оставшуюся ширину (поддерживает максимальное расширение).

Ниже приведены сценарии, описывающие влияние ограничений на различные сочетания ширины столбцов.

auto и stretch

1. Столбцы с шириной auto и stretch.

• Первый столбец с шириной auto занимает достаточно места для вывода содержимого, а второй столбец с шириной stretch занимает все пространство.

2. Столбцы только с шириной stretch.

• Столбцы, имеющие только ширину stretch, занимают оставшееся пространство после его деления на равные части.

3. auto,stretch и auto.

Ширина первого и третьего столбцов регулируется сначала для полного размещения элементов, а второй столбец с растяжением по ширине занимает оставшееся пространство.

4. Порядок отображения элементов с шириной столбцов auto.

• Столбцы с auto будут располагаться автоматически, чтобы предоставить достаточно места для отображения содержимого.
• В случае представлений изображений масштаб изображений будет уменьшаться в соответствии с оставшейся шириной.
• Примечание. Масштаб изображений будет уменьшаться только для размера изображения stretch и auto, но не в случае фиксированной ширины и высоты в пикселях.

weights и pixels

1. Столбцы с комбинированной шириной weight и pixel.

• Указанная выше карточка содержит три столбца с указанной ниже конфигурацией ширины.
• Column1: Weight 50, Column2: 100px, Column3: Weight 50
• Ширина столбца 2 определяется элементом pixel value.
• Ширина столбцов 1 и 3 настраивается в соответствии с weights и вычисляемым значением weight ratio.

2. Столбцы с атрибутами weight, pixel width и auto.

• Указанная выше карточка содержит четыре столбца с конфигурацией ширины
• Column1: Weight 50, Column2: 100px, Column3: Weight 50 и Column4: auto
• Примечание. Представление изображения с шириной столбца auto уменьшается до размера оставшегося пространства.

Порядок очередности отображения элементов с помощью атрибута width

px > weight > auto > stretch

Высота

Допустимые значения: auto и stretch.

Ниже приведены сценарии, описывающие влияние ограничений на разные сочетания высоты для элементов карточек.

1. Элементы расширяются по вертикали, если размер карточки не фиксирован.

• Оба столбца могут быть расширены по вертикали независимо от значений auto и stretch.
• Это свойство wrap для текстового блока отключено.

2. На следующей карточке свойство wrap включено для текстового блока.

Интервалы и разделители

1. Свойство spacing каждого элемента влияет на расстояние между текущим элементом и элементом, находящимся перед ним.
2. Интервал должен применяться только в том случае, если перед элементом есть другой элемент. (Например, он не должен применяться к первому элементу в массиве.)
3. Отрисовщик должен определить, сколько нужно использовать пространства, с помощью интервала в hostConfig, указанного для значения перечисления, примененного к текущему элементу.
4. Если для элемента задан параметр separator со значением true, то между текущим и предыдущим элементами должна быть нарисована видимая линия.
5. Разделительная линия должна быть нарисована с помощью container.style.default.foregroundColor.
6. Разделитель должен быть нарисован только в том случае, если элемент не является первым в массиве.
7. Интервалы. Допустимые значения: none, small, default, medium, large, extra large и padding.

• Атрибут интервала добавляет интервал между текущим и предыдущим элементом.

• Атрибут интервала не оказывает никакого влияния, если он является первым элементом в контейнере представления.

• Элементы, отмеченные стрелкой, являются первыми элементами среди одноуровневых элементов, поэтому интервалы не оказывают никакого влияния.

2. Разделитель. Возможные значения (вкл./откл.)

• Рисует разделительную линию в верхней части элемента.

3. Сочетание интервала и разделителя

• Ниже показаны ограничения использования интервала и разделителя.

• Общее расстояние между интервалами сохраняется по отношению к предоставленным значениям.
• Разделитель добавляется в середине интервала.

[Примечание. Необходимо подтвердить расстояние установки разделителя в области интервала. Примерно по середине.]

Стили контейнеров

• Предоставляет указания по стилю для контейнеров, таких как столбцы и набор столбцов.
• Допустимые значения: none, default, emphasis, good, attention, warning и accent.
• Эти предопределенные параметры стиля обеспечивают заполнение элементов в контейнере и задают цвет фона.

1. На карточке A показаны столбцы и набор столбцов без параметров стиля.
2. На карточке B показан набор столбцов со стилем Attention. Обратите внимание на заполнение в контейнере набора столбцов и на изменение цвета фона.
3. На карточке C показаны только столбцы со стилем. Как и в предыдущем случае, столбец включает в себя заполнение и изменение фона.
4. На карточке D показаны столбцы и набор столбцов с параметрами стиля.

[Примечание. Необходимо проверить, как определяется размер заполнения. Определяется ли он с помощью основного элемента? ]

Выход за край

• Это свойство позволяет контейнеру, например столбцам и набору столбцов, выходить за пределы своего родительского элемента.
• Возможные значения: on и off.

1. На карточке A показаны столбцы и набор столбцов с обычным стилем.
2. На карточке B показан первый столбец с параметром "Выход за край". Содержимое просто выходит за свои границы до пространства родительского элемента.

Размер изображения

Атрибут Size

• Допустимые значения: auto, stretch, small, medium и large.
• auto: при необходимости изображения будут масштабироваться по размеру, но не будут масштабироваться для заполнения области.
• stretch: при необходимости масштаб изображения будет уменьшаться или увеличиваться по размеру.
• small, medium и large: изображение отображается с фиксированной шириной. Ширина определяется основным элементом.

1. auto и stretch

2. Сочетание ширины столбца и размера изображения

• Как правило, столбцы с шириной stretch позволяют свободно масштабировать изображения с размером stretch.
• Столбцы с шириной auto позволяют изображениям занимать точное пространство независимо от размера изображения auto и stretch.
• Ширина столбца имеет более высокий приоритет при определении размера изображения в этом упорядочении.

Атрибут изображения Width (in pixels)

• Атрибут обеспечивает требуемую ширину изображения на экране.
• Свойство size переопределяется, если указано значение.

• Столбец с шириной auto будет иметь больший приоритет, чем stretch в предоставлении пространства для содержимого изображения в этом упорядочении.

Комбинация ширины столбца (weight и pixel) и размера изображения (auto и stretch)

• Изображения с размером auto занимают достаточно места для расширения (или уменьшения масштаба) в пределах ограничений ширины столбца weight и pixel.
• Изображения с размером stretch можно расширить, чтобы заполнить оставшееся пространство в пределах ограничений ширины столбца weight и pixel.

Сводка по расширенному макету

• Ширина столбца имеет более высокий приоритет при определении размера изображения, чем его размер (auto, stretch, min width и т. д.).
• Приоритет ширины столбца, необходимый для достаточного отображения его содержимого: px>weight>auto>stretch
• Атрибут изображения size (auto и stretch) игнорируется при условии, что указаны атрибуты изображения width и height в пикселях.
• Атрибут размера stretch изображения позволяет масштабировать изображение, только когда остается свободное место, а значение параметра не равноauto.
• Изображение растягивается до предела, при котором сохраняются пропорции в пространстве, доступном в столбце. В свою очередь, изображение разворачивается свободно по высоте.
• Атрибут Spacing не будет оказывать никакого влияния, если он является первым или единственным элементом среди одноуровневых элементов.

Действия

1. Если параметр supportsInteractivity HostConfig имеет значение false, то отрисовщик не должен отображать какие-либо действия.
2. Свойство actionsдолжно быть отображено в виде кнопок на панели действий, как правило, в нижней части карточки.
3. При нажатии кнопка должна позволить ведущему приложению обработать событие.
4. Событие должно передавать все связанные свойства с действием.
5. Событие должно передавать объект AdaptiveCard, который был выполнен.

Действие	Поведение
Action.OpenUrl	Открытие внешнего URL-адреса для просмотра.
Action.ShowCard	Запрашивает вложенную карточку для отображения пользователю.
Action.Submit	Запрашивает сбор данных от всех элементов в один объект и его отправку способом, определяемым ведущим приложением.
Action.Execute	(Добавлено в версии 1.4) Потребуйте, чтобы все элементы ввода были собраны в один объект, который затем будет отправлен через "универсальный конвейер действий".

Action.OpenUrl

1. Действие Action.OpenUrlДОЛЖНО открывать URL-адрес с помощью собственного механизма платформы.
2. Если это невозможно, оно должно породить событие в ведущем приложении для обработки открытия этого URL-адреса. Это событие должно позволить ведущему приложению переопределить поведение по умолчанию. Например, разрешить ему открыть этот URL-адрес в собственном приложении.

Action.ShowCard

1. Поддержка Action.ShowCardДОЛЖНА обеспечиваться каким-либо из способов с учетом параметра hostConfig. Существуют два режима: встроенные карточки и всплывающие окна. Встроенные карточки должны автоматически переключать видимость карточки. В режиме всплывающего окна событие должно быть передано в ведущее приложение, чтобы оно отобразило карточку каким-либо способом.

Action.Submit

• Элемент Action.Submit собирает данные поля ввода, выполняет слияние с дополнительным полем данных и отправляет событие клиенту.
• Между версиями отрисовщика ACL 1.x и 2.x присутствует существенная разница в поведении элементов.

Действие отправки выполняется, как и отправка данных в форме HTML, за исключением того, что если HTML обычно запускает HTTP-запрос POST, то адаптивные карточки в определении смысла отправки полагаются на само ведущее приложение.

1. В этом случае должно вызываться событие, когда пользователь касается вызванного действия.
2. Свойство dataдолжно быть включено в полезные данные обратного вызова.
3. Для Action.Submit отрисовщик должен собрать все входные данные в карточке и получить их значения.

• 1.x Renderer. Входные данные собираются из всех полей независимо от того, где находится поле ввода в иерархии.
• 2.x Renderer. Входные данные собираются из полей, которые присутствуют в родительском контейнере или относятся к одноуровневому элементу Action.Submit.

Action.Execute (подробности появятся позже)

Action.Execute появилось в версии 1.4. Мы предоставим руководство по реализации пакетов SDK позднее. Если у вас есть вопросы по этой теме, свяжитесь с нами.

selectAction

1. Если параметр supportedInteractivity HostConfig имеет значение false, то selectActionне должно отображаться как объект, доступный для касания.
2. Элементы Image, ColumnSet и Column предлагают свойство selectAction, которое должно выполняться, когда пользователь вызывает его, например, коснувшись элемента.

Входные данные

1. Если параметр supportsInteractivity HostConfig имеет значение false, то отрисовщик не должен отображать какие-либо управляющие элементы ввода.
2. Управляющие элементы ввода должны отображаться с максимально допустимой точностью. Например, Input.Date в идеале представит пользователю управляющий элемент выбора даты, но если это невозможно в стеке пользовательского интерфейса, то отрисовщик должен вернуться к отображению стандартного текстового поля.
3. Отрисовщик должен отображать placeholderText, если это возможно.
4. Привязка входного значения должна быть правильно экранирована.
5. До версии 1.3 в отрисовщике было НЕОБЯЗАТЕЛЬНО реализовывать проверку входных данных. Пользователи адаптивных карточек должны запланировать проверку всех полученных данных на своей стороне.
6. В версии 1.3 добавлены метки и проверка входных данных для схемы адаптивных карточек. Уделите особое внимание тому, чтобы правильно отрисовать связанную метку, указания по проверке и сообщения об ошибках.

API стилей, настройки и расширяемости

Каждый пакет SDK должен предоставлять ведущим приложениям определенный уровень гибкости, чтобы обеспечить управление общим стилем и расширение схемы по мере необходимости.

Конфигурация узла

• ТРЕБУЕМЫЕ ДЕЙСТВИЯ. Какими должны быть значения по умолчанию? Должны ли использоваться совместно? Следует ли внедрить в двоичные файлы общий файл hostConfig.JSON?

HostConfig — это общий объект конфигурации, указывающий, как отрисовщик адаптивных карточек создает пользовательский интерфейс.

Это позволяет отрисовщикам на разных платформах и устройствах использовать свойства, которые независимы от платформы. Кроме того, это позволяет создавать наборы инструментов, которые дают представление о внешнем виде и функциях карточки в конкретной среде.

1. Отрисовщики должны предоставлять параметр HostConfig ведущим приложениям.
2. Все элементы должны быть стилизованы согласно соответствующим параметрам HostConfig.

Стиль собственной платформы

1. Каждый тип элемента должен привязывать стиль собственной платформы к созданному элементу пользовательского интерфейса. Например, в HTML мы добавили класс CSS к типам элементов, а в XAML мы присваиваем конкретный стиль.

Расширение среды

1. Отрисовщик должен позволять ведущим приложениям переопределять отрисовщики элементов по умолчанию. Например, заменить отрисовку TextBlock собственной логикой.
2. Отрисовщик должен позволять ведущим приложениям регистрировать пользовательские типы элементов. Например, добавить поддержку пользовательского элемента Rating.
3. Отрисовщик должен позволять ведущим приложениям удалять поддержку элемента по умолчанию. Например, удалить элемент Action.Submit, если его поддержка не нужна.

События

1. Отрисовщик должен запускать событие при изменении видимости элемента, позволяя ведущему приложению прокрутить карточку до нужного места.