Especificación del representador de Tarjetas adaptables

La siguiente especificación describe cómo implementar un representador de Tarjetas adaptables en cualquier plataforma de interfaz de usuario nativa.

Importante

Este contenido es un trabajo en curso y puede que falten algunos detalles. Si tiene preguntas o comentarios, póngase en contacto con nosotros.

Análisis de JSON

Condiciones del error

1. Un analizador DEBE comprobar que se trata de contenido JSON válido.
2. Un analizador DEBE validar el esquema (propiedades obligatorias, etc.).
3. Los errores anteriores DEBEN notificarse a la aplicación host (excepción o equivalente).

Tipos desconocidos

1. Si se encuentran "tipos" desconocidos, DEBEN QUITARSE del resultado.
2. Cualquier modificación de la carga (como la anterior) DEBE notificarse como advertencia en la aplicación host.

Propiedades desconocidas

1. Un analizador DEBE incluir propiedades adicionales en los elementos.

Consideraciones adicionales

1. La propiedad speak PUEDE contener marcado SSML y DEBE devolverse a la aplicación host como se especifica.

Análisis de la configuración de host

1. TODO

Control de versiones

1. Un representador DEBE implementar una versión determinada del esquema.
2. El constructor AdaptiveCardDEBE proporcionar a la propiedad version un valor predeterminado basado en la versión de esquema actual.
3. Si un representador encuentra una propiedad version en AdaptiveCard que sea superior a la versión admitida, DEBE devolver fallbackText en su lugar.

Representación

Una instancia de AdaptiveCard consta de body y actions. body es una colección de CardElement que un representador enumerará y representará en orden.

1. Cada elemento DEBE ajustarse al ancho de su elemento primario (considera display: block en HTML).
2. Un representador DEBE omitir todos los tipos de elementos desconocidos que encuentre y seguir representando el resto de la carga.

Texto, TextBlock y RichTextBlock

1. TextBlock DEBE ocupar una sola línea a menos que la propiedad wrap sea true.
2. El bloque de texto DEBE recortar el texto sobrante con puntos suspensivos (...).

Markdown.

1. Las Tarjetas adaptables permiten un subconjunto de Markdown y DEBEN admitirse en TextBlock.
2. RichTextBlock NO es compatible con Markdown y se le debe aplicar estilo a través de las propiedades que se exponen.
3. Consulta los requisitos de Markdown completos.

Funciones de formato

1. TextBlock permite funciones de formato de fecha y hora que se DEBEN admitir en cada representador.
2. TODOS LOS ERRORES DEBEN mostrar la cadena sin formato en la tarjeta. No se intentó ningún mensaje descriptivo. (El objetivo es hacer que el desarrollador sepa inmediatamente que hay un problema).

Imágenes

1. Un representador DEBE permitir que las aplicaciones host sepan cuándo se han descargado todas las imágenes HTTP y se ha "representado completamente" la tarjeta.
2. Un representador DEBE inspeccionar el parámetro maxImageSize de la configuración de host al descargar imágenes HTTP.
3. Un representador DEBE admitir .png y .jpeg.
4. Un representador DEBE admitir imágenes .gif.

Comportamiento de diseño avanzado

El representador DEBE tener cuidado con los siguientes comportamientos al representar elementos de tarjeta relacionados con los atributos que se mencionan en este documento.

El representador debe administrar las restricciones teniendo en cuenta diversos factores, como la configuración del margen, el relleno, el alto y el ancho, etc., de los componentes de la tarjeta y sus elementos secundarios.

Ancho

1. Valores permitidos: auto, stretch y valores fijos en términos de pixels y weight.
2. El valor auto proporciona espacio suficiente para la expansión del ancho (admite la expansión mínima).
3. El valor stretch ocupa el ancho restante (admite la expansión máxima).

En los siguientes escenarios se describe cómo se ven afectadas las restricciones con combinaciones de ancho diferentes para las columnas.

auto frente a stretch

1. Columnas con anchos auto y stretch.

• La primera columna con ancho auto ocupa espacio suficiente para mostrar el contenido y la segunda columna con ancho stretch ocupa todo el espacio.

2. Columnas solo con ancho stretch

• Las columnas solo con ancho stretch ocupan los espacios restantes después de la división por igual.

3. auto,stretch y auto

Primero se ajusta el ancho de las columnas primera y tercera para acomodar los elementos suficientemente. A continuación, la segunda columna con el ancho ajustado ocupa el espacio restante.

4. Orden de visualización de los elementos con columnas de ancho auto

• Las columnas con ancho auto se colocarán para proporcionar espacio suficiente para que el contenido se represente.
• En el caso de las vistas de imagen, las imágenes se reducen para ajustarse al ancho restante.
• Nota: Las imágenes se reducen solo para el tamaño de imagen stretch y auto, pero no para el ancho y el alto fijos en píxeles.

weights frente a pixels

1. Columnas con combinación de ancho weight y pixel

• La tarjeta anterior tiene tres columnas con la siguiente configuración de ancho:
• Column1: Weight 50, , Column2: 100px, Column3: Weight 50
• El ancho de la columna 2 viene determinado por el valor pixel value.
• El ancho de las columnas 1 y 3 se ajusta en función del valor de weights y el valor calculado de weight ratio.

2. Columnas con los atributos weight, pixel width y auto

• La tarjeta anterior tiene cuatro columnas con la siguiente configuración de ancho:
• Column1: Weight 50, Column2: 100px, Column3: Weight 50 y Column4: auto.
• Nota: La vista de imagen con la columna de ancho auto se reduce para ajustarse al espacio restante.

Orden de prioridad de visualización de elementos con el atributo de ancho

px > weight > auto > stretch

Height

Valores permitidos: auto y stretch.

En los escenarios siguientes se describe cómo se ven afectadas las restricciones con diferentes combinaciones de alto para los elementos de tarjeta.

1. Los elementos se expanden verticalmente con libertad cuando la tarjeta no tiene un alto fijo.

• Ambas columnas pueden expandirse verticalmente de forma suficiente, independientemente de los valores de auto y stretch.
• La propiedad wrap está deshabilitada para el bloque de texto.

2. La tarjeta siguiente tiene la propiedad wrap habilitada para el bloque de texto.

Espaciado y separadores

1. La propiedad spacing de cada elemento influye en la cantidad de espacio que hay entre el elemento ACTUAL y el ANTERIOR.
2. El espaciado SOLO DEBE aplicarse cuando realmente hay un elemento que lo precede. (Por ejemplo, no se aplicará al primer elemento de una matriz).
3. Un representador DEBE buscar la cantidad de espacio que se va a usar del espaciado hostConfig del valor de enumeración aplicado al elemento actual.
4. Si el elemento tiene un valor de separator establecido en true, se DEBE dibujar una línea visible entre el elemento actual y el anterior.
5. La línea de separación DEBE dibujarse mediante container.style.default.foregroundColor.
6. SOLO DEBE dibujarse un separador si el elemento NO ES el primero de la matriz.
7. Spacing: los valores permitidos son none, small, default, medium, large, extra large y padding.

• El atributo Spacing agrega espaciado entre este elemento y el anterior.

• El atributo Spacing no tiene ningún efecto cuando es el primer elemento del contenedor de vistas.

• Los elementos marcados con flecha son los primeros entre los del mismo nivel, por lo que el espaciado no tiene ningún efecto.

2. Separator: valores posibles (opción de alternancia on/off).

• Dibuja una línea de separación en la parte superior del elemento.

3. Combinación de espaciado y separador

• A continuación se muestran las restricciones de combinación de espaciado y separador

• La distancia de espaciado total se mantiene con respecto a los valores proporcionados.
• El separador se agrega en el medio de la distancia espaciada.

[Nota. Debe confirmar la distancia en la que se inserta el separador en el área de espaciado. Parece el centro.]

Estilos de contenedor

• Proporciona sugerencias de estilo para contenedores como las columnas y el conjunto de columnas.
• Los valores permitidos son none, default, emphasis, good, attention, warning y accent.
• Estas opciones de estilo predefinidas proporcionan relleno para los elementos del contenedor y del color de fondo.

1. La tarjeta A ilustra las columnas y el conjunto de columnas sin opciones de estilo.
2. La tarjeta B ilustra el conjunto de columnas con el estilo Atención. Observe el relleno dentro del contenedor del conjunto de columnas y el cambio en el color de fondo.
3. La tarjeta C muestra las columnas con estilo solamente. De forma similar al ejemplo anterior, la columna incluye relleno y cambio de fondo.
4. La tarjeta D ilustra las columnas y el conjunto de columnas, ambos con opciones de estilo.

[Nota. Debe comprobar cómo se determina la cantidad de relleno. ¿La determina el host? ]

A sangre

• Esta propiedad permite que el contenedor, como las columnas y el conjunto de columnas, se configure con impresión a sangre en su elemento primario.
• Los valores posibles son on y off.

1. La tarjeta A ilustra las columnas y el conjunto de columnas con un estilo normal.
2. La tarjeta B ilustra la primera columna con la opción a sangre. El contenido solo se configura con impresión a sangre en los límites con el elemento primario.

Tamaño de la imagen

Atributo Size

• Valores permitidos: auto, stretch, small, medium, large.
• auto : las imágenes se reducirán verticalmente para ajustarse si es necesario, pero no se escalarán verticalmente para rellenar el área.
• stretch : imagen con reducción vertical y vertical para ajustarse según sea necesario.
• small, medium y large: la imagen se muestra con un ancho fijo, donde el host determina el ancho.

1. auto frente a stretch

2. Combinación de ancho de columna y tamaño de imagen

• Por lo general, las columnas con ancho stretch permiten que las imágenes se escalen verticalmente de forma libre con el tamaño stretch.
• Las columnas con el ancho auto permiten que la imagen ocupe el espacio exacto, independientemente del tamaño auto y stretch de la imagen.
• El ancho de columna tiene prioridad a la hora de determinar el tamaño de la imagen en esta disposición.

Atributo Width (in pixels) de la imagen

• Proporciona el ancho de pantalla deseado para la imagen.
• La propiedad size se invalida cuando se especifica un valor.

• La columna con el ancho auto tendrá prioridad frente a stretch a la hora de proporcionar espacio para el contenido de la imagen en esta disposición.

Combinación de ancho de columna (weight y pixel) y tamaño de imagen (auto y stretch)

• Las imágenes con el tamaño auto ocupan espacio suficiente para la expansión (o la reducción) dentro de las restricciones de columna de ancho weight y pixel.
• Las imágenes con el tamaño stretch pueden expandirse para rellenar el espacio restante dentro del ancho de columna weight y pixel.

Resumen de diseño avanzado

• A la hora de determinar el tamaño de la imagen, el ancho de columna tiene prioridad sobre el propio tamaño de imagen (auto, stretch, min width, etc.).
• Prioridad del ancho de columna usado para mostrar su contenido de manera suficiente: px>weight>auto>stretch
• El valor de size (auto, stretch) de la imagen se ignora cuando se proporciona el valor de width y height de la imagen en px.
• El atributo de tamaño stretch de la imagen solo escalará verticalmente la imagen cuando haya espacio restante y el ancho de columna no sea auto.
• Una imagen se estira hasta el límite en el que mantiene su relación de aspecto en el espacio disponible en la columna. A su vez, el alto se expande libremente.
• El atributo Spacing no tendrá ningún efecto cuando sea el primer o el único elemento entre los del mismo nivel.

Acciones

1. Si HostConfig supportsInteractivity es false, un representador NO DEBE representar ninguna acción.
2. La propiedad actionsDEBE representarse como un botón en algún tipo de barra de acciones, normalmente en la parte inferior de la tarjeta.
3. Cuando se pulsa un botón, DEBE permitir que la aplicación host controle el evento.
4. El evento DEBE pasar todas las propiedades asociadas con la acción.
5. El evento DEBE pasar a lo largo de la instancia AdaptiveCard que se ha ejecutado.

Action	Comportamiento
Action.OpenUrl	Abre una dirección URL externa para verla.
Action.ShowCard	Solicita que se muestre una tarjeta secundaria al usuario.
Action.Submit	Solicita que se recopilen todos los elementos en un objeto que le enviamos a través de algún método definido por la aplicación host.
Action.Execute	(Se introdujo en la versión 1.4) Solicita que se recopilen todos los elementos de entrada en un objeto que después se le envía a través de la "canalización de acciones universal".

Action.OpenUrl

1. Action.OpenUrl DEBE abrir una dirección URL mediante el mecanismo de plataforma nativa.
2. Si esto no es posible, DEBE desencadenar un evento en la aplicación host para controlar la apertura de la dirección URL. Este evento DEBE permitir que la aplicación host invalide el comportamiento predeterminado. Por ejemplo, permite que abran la dirección URL dentro de su propia aplicación.

Action.ShowCard

1. Action.ShowCard DEBE admitirse de alguna manera, según el valor de hostConfig. Hay dos modos: insertado y emergente. Las tarjetas insertadas DEBEN alternar la visibilidad de la tarjeta automáticamente. En el modo emergente, se DEBE desencadenar un evento en la aplicación host para mostrar la tarjeta de alguna manera.

Action.Submit

• El elemento Action.Submit recopila los campos de entrada, realiza la combinación con el campo de datos opcional y envía un evento al cliente.
• Existe una diferencia significativa en el comportamiento del elemento entre la versión 1.x y la 2.x del representador de ACL.

La acción de envío se comporta como un envío de formulario HTML, con la excepción de que cuando el código HTML normalmente desencadena un HTTP POST, las Tarjetas adaptables lo dejan en cada aplicación host para determinar qué significa "enviar".

1. Cuando esta acción DEBE provocar un evento, el usuario pulsa la acción invocada.
2. La propiedad dataDEBE incluirse en la carga de devolución de llamada.
3. Para Action.Submit, un representador DEBE reunir todas las entradas de la tarjeta y recuperar sus valores.

• 1.x Renderer: las entradas se recopilan de todos los campos, independientemente del lugar de la jerarquía en el que esté presente el campo de entrada.
• 2.x Renderer: las entradas se recopilan de los campos presentes en el contenedor primario o como un elemento del mismo nivel del elemento Action.Submit.

Action.Execute (información detallada más adelante)

Action.Execute se introdujo en la versión 1.4. En una fecha posterior, proporcionaremos una guía de implementación para los SDK. Si tiene preguntas sobre este tema, póngase en contacto.

selectAction

1. Si la configuración de host supportedInteractivity es false, un valor de selectAction NO DEBE representarse como un destino táctil.
2. Image, ColumnSet y Column ofrecen una propiedad selectAction, que DEBE ejecutarse cuando el usuario la invoca; por ejemplo, al pulsar en el elemento.

Entradas

1. Si HostConfig supportsInteractivity es false, un representador NO DEBE representar ninguna entrada.
2. Las entradas DEBEN representarse con la mayor fidelidad posible. Por ejemplo, Input.Date idealmente ofrecería un selector de fecha a un usuario, pero si esto no es posible en la pila de la interfaz de usuario, el representador DEBE revertirse para representar un cuadro de texto estándar.
3. Un representador DEBE mostrar placeholderText si es posible.
4. El enlace del valor de entrada DEBE tener un carácter de escape correcto.
5. Antes de la versión 1.3, un representador NO tiene que implementar la validación de la entrada. Los usuarios de Tarjetas adaptables deben planear la validación de los datos recibidos en su extremo.
6. Las etiquetas de entrada y la validación se introdujeron en la versión 1.3 del esquema de Tarjetas adaptables. Se debe tener cuidado adicional al representar la etiqueta asociada, las sugerencias de validación y los mensajes de error.

API de estilos, personalización y extensibilidad

Cada SDK debe proporcionar un cierto nivel de flexibilidad para las aplicaciones host a fin de controlar el estilo general y ampliar el esquema según sea necesario.

Configuración de host

• TAREA PENDIENTE: ¿cuáles son los valores predeterminados? ¿Se deben compartir todos? ¿Se debe insertar un archivo hostConfig.json común en los archivos binarios?

HostConfig es un objeto de configuración compartido que especifica cómo un representador de Tarjetas adaptables genera una interfaz de usuario.

Esto permite compartir las propiedades que son independientes de la plataforma entre los representadores en diferentes plataformas y dispositivos. También permite crear las herramientas, lo que te da una idea de la apariencia y el funcionamiento de la tarjeta para un ambiente determinado.

1. Los representadores DEBEN exponer un parámetro de configuración de host para las aplicaciones host.
2. Todos los elementos DEBEN tener diseñarse en función de sus valores de configuración de host respectivos.

Estilo de las plataformas nativas

1. Cada tipo de elemento DEBE asociar un estilo de plataforma nativa con el elemento de la interfaz de usuario generado. Por ejemplo, en HTML hemos agregado una clase CSS a los tipos de elementos y en XAML, asignamos un estilo específico.

Extensibilidad

1. Un representador DEBE permitir que las aplicaciones host invaliden los representadores de elementos predeterminados. Por ejemplo, reemplazar la representación TextBlock por su propia lógica.
2. Un representador DEBE permitir que las aplicaciones host registren tipos de elementos personalizados. Por ejemplo, agregar compatibilidad para un elemento Rating personalizado.
3. Un representador DEBE permitir que las aplicaciones host quiten la compatibilidad para un elemento predeterminado. Por ejemplo, quitar Action.Submit si no se quiere que se admita.

Eventos

1. Un representador DEBE desencadenar un evento cuando cambia la visibilidad de un elemento, lo que permite a la aplicación host desplazar la tarjeta hacia la posición.