Especificação do renderizador de cartão adaptativo

A especificação a seguir descreve como implementar um renderizador de cartão adaptável em qualquer plataforma de interface do usuário nativa.

Análise JSON

Condições de erro

1. Um analisador DEVE verificar se o conteúdo JSON é válido
2. Um analisador DEVE validar em relação ao esquema (propriedades necessárias, etc.)
3. Os erros acima DEVEM ser relatados ao aplicativo host (exceção ou equivalente)

Tipos desconhecidos

1. Se forem encontrados "tipos" desconhecidos, eles DEVEM SER DESCARTADOS do resultado
2. Quaisquer alterações da carga útil (como acima) DEVEM ser relatadas como avisos para o aplicativo host

Propriedades desconhecidas

1. Um analisador DEVE incluir propriedades adicionais em elementos

Considerações adicionais

1. A speak propriedade PODE conter marcação SSML e DEVE ser retornada ao aplicativo host conforme especificado

Analisando a configuração do host

1. TODO

Gestão de Versões

1. Um renderizador DEVE implementar uma versão específica do esquema.
2. O AdaptiveCard construtor MUST deve atribuir à version propriedade um valor pré-definido com base na versão do esquema atual
3. Se um renderizador encontrar uma version propriedade na AdaptiveCard que é maior do que a versão suportada, ele DEVE retornar o fallbackText em vez disso.

Renderização

Um AdaptiveCard consiste em um body e actions. O body é uma coleção de CardElements que um renderizador irá enumerar e renderizar em ordem.

1. Cada elemento DEVE se estender até a largura de seu pai (pense display: block em HTML).
2. Um renderizador DEVE ignorar quaisquer tipos de elementos desconhecidos que encontrar e continuar a renderizar o restante da carga.

Text, TextBlock e RichTextBlock

1. Um TextBlock DEVE ocupar uma única linha, a menos que a wrap propriedade seja true.
2. O bloco de texto DEVE aparar qualquer excesso de texto com reticências (...)

Markdown

1. Os cartões adaptáveis permitem um subconjunto de Markdown e deveriam ser suportados no TextBlock.
2. RichTextBlock NÃO suporta Markdown e deve ser estilizado usando as propriedades expostas.
3. Ver requisitos de markdown completos

Funções de formatação

1. TextBlock permite funções de formatação DATE/TIME que DEVEM ser suportadas em cada renderizador.
2. TODAS AS FALHAS DEVEM exibir a string bruta no cartão. Nenhuma tentativa de mensagem amigável. (O objetivo é fazer com que o desenvolvedor imediatamente ciente de que há um problema)

Imagens

1. Um renderizador DEVE permitir que os aplicativos host saibam quando todas as imagens HTTP foram baixadas e o cartão está "totalmente renderizado"
2. Um renderizador DEVE inspecionar o parâmetro Host Config maxImageSize ao baixar imagens HTTP
3. Um renderizador DEVE suportar .png e .jpeg
4. Um renderizador DEVE suportar .gif imagens

Comportamento avançado de layout

O renderizador DEVE tomar cuidado com os seguintes comportamentos ao renderizar elementos de cartão em relação aos atributos mencionados neste documento.

O renderizador deve gerenciar Restrições levando em conta os vários fatores, como margem, preenchimento, altura e largura, e a configuração dos elementos do cartão e seus filhos.

Largura

1. Valores permitidos - auto, stretch e valores fixos em termos de pixels e weight
2. auto fornece espaço suficiente para expansão de largura (suporta expansão mínima)
3. stretch ocupa a largura restante (suporta expansão máxima)

Os cenários abaixo descrevem como as restrições são afetadas com diferentes combinações de largura para colunas

auto vs stretch

1. Colunas com largura de auto e stretch.

• A primeira coluna com auto largura ocupa espaço suficiente para exibir o conteúdo e a segunda coluna com stretch largura ocupa todo o espaço.

2. Colunas com apenas stretch de largura

• Colunas com apenas largura de estiramento ocupam os espaços restantes depois de dividi-lo igualmente.

3. auto,stretch e auto

A largura da primeira e terceira colunas é ajustada primeiro para acomodar suficientemente os elementos e a segunda coluna com largura esticada ocupa o espaço restante.

4. Ordem de exibição de elementos com auto colunas de largura

• Colunas com auto irão posicionar-se para fornecer amplo espaço para o conteúdo ser exibido.
• No caso de visualizações de imagem, as imagens serão reduzidas para caber na largura restante.
• Observação: As imagens serão reduzidas apenas para os tamanhos de imagem de stretch e auto, mas não para larguras e alturas fixas em pixels.

weights vs pixels

1. Colunas com a combinação de largura weight e pixel

• O cartão acima tem três colunas com a seguinte configuração de largura -
• Column1: Weight 50, Column2: 100px, Column3: Weight 50
• A largura da coluna 2 é determinada pela pixel value
• A largura das colunas 1 e 3 é ajustada com base no weights e no cálculo weight ratio.

2. Colunas com atributos weight, pixel width e auto

• O cartão acima tem quatro colunas com a seguinte configuração de largura -
• Column1: Weight 50, Column2: 100px, Column3: Weight 50e Column4: auto
• Nota: A visualização da imagem com a coluna de largura auto é redimensionada para se ajustar ao espaço restante.

Ordem de precedência da exibição de elementos com o atributo width

px > weight > auto > stretch

Altura

Valores permitidos - auto e stretch

Os cenários abaixo descrevem como as restrições são afetadas com diferentes combinações de altura para elementos de cartão

1. Os elementos expandem-se livremente verticalmente quando o cartão não é de altura fixa

• Ambas as colunas podem expandir-se verticalmente de forma suficiente, independentemente dos valores auto e stretch
• Isto acontece com a propriedade wrap desativada para o bloco de texto.

2. O cartão abaixo tem a wrap propriedade ativada para o bloco de texto.

Espaçamento e Separador

1. A spacing propriedade em cada elemento influencia a quantidade de espaço entre o elemento CURRENT e aquele ANTES dele.
2. O espaçamento SÓ DEVE ser aplicado quando realmente houver um elemento que o precede. (Por exemplo, não se aplica ao primeiro item de uma matriz)
3. Um renderizador DEVE procurar a quantidade de espaço a ser usada no espaçamento para o valor de enum aplicado ao elemento atual.
4. Se o elemento tiver um separator valor de , então uma linha visível DEVE ser desenhada trueentre o elemento atual e o anterior.
5. A linha separadora DEVE ser traçada utilizando o container.style.default.foregroundColor.
6. Um separador SÓ DEVE ser desenhado se o item NÃO for o primeiro da matriz.
7. Espaçamento - Valores permitidos none, small, default, medium, large, extra large e padding

• O atributo Espaçamento adiciona espaçamento entre este elemento e o elemento anterior.

• O atributo Espaçamento não tem qualquer efeito quando é o primeiro elemento no contêiner de exibição.

• Os elementos marcados com seta são os primeiros elementos entre seus irmãos, então o espaçamento não tem efeito.

2. Separador - Valores possíveis (alternância on/off)

• Desenha uma linha separada na parte superior do elemento.

3. Combinação de espaçamento e separador

• As restrições do espaçamento e da combinação separadora são ilustradas abaixo.

• A distância de espaçamento total é mantida em relação aos valores fornecidos.
• O separador é adicionado no meio da distância entre os espaços.

[Observação. É necessário confirmar a distância em que o separador está inserido na área de espaçamento. Parece o meio]

Estilos de contêiner

• Fornece dicas de estilo para contêineres, como colunas e conjunto de colunas
• Valores permitidos none, default, emphasis, good, attention, warning e accent
• Essas opções de estilo predefinidas fornecem preenchimento para os elementos dentro do contêiner e da cor de plano de fundo

1. O cartão A ilustra colunas e conjuntos de colunas sem opções de estilo
2. O cartão B ilustra o conjunto de colunas com o estilo Atenção . Observe o preenchimento dentro do contêiner do conjunto de colunas e a alteração na cor do plano de fundo.
3. O Cartão C ilustra colunas apenas com estilização. Semelhante à anterior, a coluna possui preenchimento e mudança de fundo.
4. O cartão D ilustra colunas e conjuntos de colunas, ambos com opções de estilo.

[Observação. Precisa verificar como a quantidade de padding é determinada. É determinado pelo anfitrião? ]

Sangramento

• Esta propriedade permite que o contentor, como colunas e conjunto de colunas, sobressaia através do seu progenitor.
• Valores on possíveis e off.

1. O cartão A ilustra colunas e conjuntos de colunas com estilo regular.
2. O cartão B ilustra a primeira coluna com a opção de sangria. O conteúdo apenas sangra através de seus limites para os de seus pais.

Tamanho da imagem

Atributo Size

• Valores permitidos - auto, stretch, small, medium, large
• auto: As imagens serão ajustadas para caber se necessário, mas não serão aumentadas para preencher a área.
• stretch : Imagem com escala reduzida e aumentada para caber conforme necessário.
• small largee medium : A imagem é exibida com uma largura fixa, onde a largura é determinada pelo host.

1. auto vs stretch

2. Combinação de largura da coluna e tamanho da imagem

• Geralmente, as colunas com stretch largura permitem que as imagens escalonem livremente com stretch o tamanho.
• Colunas com largura auto permitem que a imagem ocupe o espaço exato, independentemente do tamanho da imagem auto e stretch.
• A largura da coluna tem mais precedência na determinação do tamanho da imagem neste arranjo.

Atributo Image Width (in pixels)

• Isso fornece a largura desejada da imagem na tela.
• size propriedade é substituída quando um valor é especificado

• A coluna com largura auto terá mais precedência do que a stretch em fornecer espaço para o conteúdo de imagem neste arranjo.

Combinação de largura da coluna (peso e pixel) e tamanho da imagem (automático e estiramento)

• Imagens do tamanho de auto ocupam espaço suficiente para expansão (ou redução de escala) dentro das restrições de coluna e largura de weightpixel.
• As imagens com tamanho stretch podem ser expandidas para preencher o espaço restante dentro das restrições de largura das colunas weight e pixel.

Resumo do layout avançado

• A largura da coluna tem mais importância ao decidir o tamanho da imagem do que o tamanho da própria imagem (auto, esticar, largura mínima, etc.).
• A prioridade da largura da coluna necessária para exibir o seu conteúdo de forma suficiente - px>weight>auto>stretch
• Imagem size (auto, stretch) é ignorada quando Imagem width e height em px é fornecida.
• O atributo de tamanho da imagem stretch aumentará a imagem somente quando houver espaço restante e a coluna automática nãoauto for.
• Uma imagem se estende até o limite onde mantém sua proporção no espaço disponível na coluna. Por sua vez, a altura expande-se livremente.
• Spacing atributo não terá qualquer efeito quando for o primeiro ou o único elemento entre seus irmãos.

Ações

1. Se HostConfig supportsInteractivity for false, um renderizador não deve renderizar nenhuma ação.
2. A actions propriedade DEVE ser renderizada como botões em algum tipo de barra de ação, geralmente na parte inferior do cartão.
3. Quando um botão é tocado, ele DEVE permitir que o aplicativo host manipule o evento.
4. O evento DEVE transmitir todas as propriedades associadas à ação
5. O evento DEVE transmitir o AdaptiveCard que foi executado

Ação.OpenUrl

1. Action.OpenUrl DEVE abrir uma URL usando o mecanismo de plataforma nativa
2. Se isso não for possível, ele DEVE gerar um evento para o aplicativo host para lidar com a abertura da URL. Esse evento DEVE permitir que o aplicativo host substitua o comportamento padrão. Por exemplo, deixe-os abrir o URL dentro de seu próprio aplicativo.

Action.ShowCard

1. Action.ShowCard DEVE ser suportado de alguma forma, com base na configuração hostConfig. Existem dois modos: inline e pop-up. As placas em linha DEVEM alternar a visibilidade da placa automaticamente. No modo pop-up, um evento DEVE ser disparado para o aplicativo host para mostrar o cartão de alguma forma.

Ação.Enviar

• Action.Submit reúne campos de entrada, mescla com campo de dados opcional e envia um evento para o cliente.
• Uma diferença significativa no comportamento do elemento está presente entre a versão 1.x e 2.x do renderizador ACL.

A ação de envio comporta-se como o envio de um formulário HTML, exceto que, quando o HTML normalmente aciona uma publicação HTTP, o Cartão Adaptável deixa ao critério de cada aplicação anfitriã determinar o que "enviar" significa para eles.

1. Quando isso DEVE gerar um evento, o usuário toca na ação invocada.
2. A data propriedade DEVE ser incluída na carga útil do callback.
3. Para Action.Submit, um renderizador DEVE reunir todas as entradas no cartão e recuperar seus valores.

• 1.x Renderer - As entradas são coletadas de todos os campos, independentemente de onde na hierarquia o campo de entrada está presente.
• 2.x Renderer - As entradas são recolhidas de campos presentes no contêiner principal ou como um elemento irmão do elemento Action.Submit.

Action.Execute (Detalhes mais tarde)

Action.Execute foi introduzido na versão 1.4. Forneceremos orientações de implementação para SDKs em uma data posterior. Por favor, entre em contato se você tiver dúvidas sobre este tópico.

selecionarAção

1. Se Host Config supportedInteractivity é false, então um selectActionMUST NOT renderizar como um alvo de toque.
2. Image, ColumnSet e Column oferecem uma propriedade selectAction, que DEVE ser executada quando o utilizador a invocar, por exemplo, tocando no elemento.

Insumos

1. Se HostConfig supportsInteractivity é false um renderizador NÃO DEVE renderizar nenhuma entrada.
2. As entradas DEVEM renderizar com a maior fidelidade possível. Por exemplo, o Input.Date ideal seria oferecer um seletor de data para um usuário, mas se isso não for possível na pilha da interface do usuário, o renderizador DEVE voltar a renderizar uma caixa de texto padrão.
3. Um renderizador DEVE exibir o placeholderText se possível
4. A vinculação do valor de entrada DEVE ser devidamente escapada
5. Antes da v1.3, um renderizador NÃO precisa implementar a validação da entrada. Os utilizadores de Adaptive Cards devem planear validar quaisquer dados recebidos do seu lado.
6. Os Rótulos de Entrada e a Validação foram introduzidos na v1.3 do Adaptive Cards Schema. Cuidado extra deve ser tomado para renderizar o rótulo associado, dicas de validação e mensagens de erro.

APIs de estilo, personalização e extensibilidade

Cada SDK deve fornecer um certo nível de flexibilidade para Host Apps para controlar o estilo geral e estender o esquema como eles acharem melhor.

Configuração do Anfitrião

• TODO: Quais devem ser os padrões? Devem todos partilhá-la? Devemos incorporar um arquivo de hostConfig.json comum nos binários?

HostConfig é um objeto de configuração compartilhado que especifica como um renderizador de cartão adaptável gera a interface do usuário.

Isso permite que propriedades que são agnósticas de plataforma sejam compartilhadas entre renderizadores em diferentes plataformas e dispositivos. Permite ainda a criação de ferramentas que lhe dão uma ideia de como seria a aparência e a sensação do cartão num determinado ambiente.

1. Os renderizadores DEVEM expor um parâmetro Host Config para hospedar aplicativos
2. Todos os elementos DEVEM ser estilizados de acordo com suas respetivas configurações de Configuração do Host

Estilo de plataforma nativo

1. Cada tipo de elemento DEVE anexar um estilo de plataforma nativo ao elemento da interface do usuário gerado. Por exemplo, em HTML adicionamos uma classe CSS aos tipos de elementos e, em XAML, atribuímos um Style específico.

Extensibilidade

1. Um renderizador DEVE permitir que os aplicativos host substituam os renderizadores de elementos padrão. Por exemplo, substitua a renderização de TextBlock com a sua própria lógica.
2. Um renderizador DEVE permitir que os aplicativos host registrem tipos de elementos personalizados. Por exemplo, adicionar suporte para um elemento personalizado Rating
3. Um renderizador DEVE permitir que os aplicativos host removam o suporte para um elemento padrão. Por exemplo, remova Action.Submit se eles não quiserem que ele seja suportado.

Eventos

1. Um renderizador DEVE disparar um evento quando a visibilidade de um elemento for alterada, permitindo que o aplicativo host role o cartão para a posição.