Especificação do renderizador de Cartões Adaptáveis

A especificação a seguir descreve como implementar um renderizador de Cartões Adaptáveis em qualquer plataforma de interface do usuário nativa.

Importante

Este conteúdo é um trabalho em andamento e podem estar faltando alguns detalhes. Entre em contato conosco caso tenha dúvidas ou comentários.

Como analisar JSON

Condições de erro

1. Um analisador PRECISA verificar se o conteúdo em questão é um JSON válido
2. Um analisador PRECISA ser validado com relação ao esquema (propriedades obrigatórias, etc)
3. Os erros acima PRECISAM ser relatados para o aplicativo host (exceção ou equivalente)

Tipos desconhecidos

1. Se "tipos" desconhecidos forem encontrados, eles PRECISARÃO SER REMOVIDOS do resultado
2. Qualquer alteração ao conteúdo (como acima) PRECISA ser relatada como avisos para o aplicativo host

Propriedades desconhecidas

1. Um analisador PRECISA incluir propriedades adicionais em elementos

Considerações adicionais

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

Analisando a Configuração do Host

1. TODO

Controle de versão

1. Um renderizador PRECISA implementar uma versão específica do esquema.
2. O construtor AdaptiveCardPRECISA dar à propriedade version um valor padrão com base na versão do esquema atual
3. Se um renderizador encontrar uma propriedade version no AdaptiveCard que seja maior do que a versão compatível, ele PRECISARÁ retornar o fallbackText em vez disso.

Tempo de

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

1. Cada elemento PRECISA ser alongado para a largura de seu pai (assim como display: block em HTML).
2. Um renderizador PRECISA ignorar todos os tipos de elementos desconhecidos que encontrar e continuar renderizando o restante do conteúdo.

Text, TextBlock e RichTextBlock

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

Markdown

1. Os Cartões Adaptáveis permitem um subconjunto de Markdown e DEVEM ser compatíveis com TextBlock.
2. RichTextBlock NÃO dá suporte a Markdown e deve ser estilizado usando as propriedades expostas.
3. Confira os requisitos de Markdown

Funções de formatação

1. TextBlock permite funções de formatação de DATA/HORA que PRECISAM ser compatíveis com todos os renderizadores.
2. TODAS AS FALHAS PRECISAM exibir a cadeia de caracteres bruta no cartão. Não houve tentativa de exibir nenhuma mensagem amigável. (A meta é fazer com que o desenvolvedor saiba imediatamente que há um problema)

Imagens

1. Um renderizador DEVE permitir que aplicativos host saibam quando todas as imagens HTTP foram baixadas e o cartão está "totalmente renderizado"
2. Um renderizador PRECISA inspecionar o parâmetro maxImageSize de configuração do host ao baixar imagens HTTP
3. Um renderizador PRECISA dar suporte a .png e .jpeg
4. Um renderizador DEVE dar suporte a imagens .gif

Comportamento de layout avançado

O Renderizador PRECISA ter cuidado com os comportamentos a seguir ao renderizar elementos de cartão com relação aos atributos mencionados neste documento.

O renderizador deve gerenciar as restrições levando em conta os diversos fatores, como margem, preenchimento, altura e largura e outros, bem como a configuração dos elementos do cartão e dos respectivos filhos.

Width

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

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

auto versus stretch

1. Colunas com largura auto e stretch.

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

2. Colunas com apenas a largura stretch

• As colunas com apenas a largura stretch ocupam os espaços restantes depois de dividirem o espaço igualmente.

3. auto, stretch e auto

A largura da primeira e da terceira colunas é ajustada primeiro para acomodar os elementos de maneira suficiente e a segunda coluna com largura de ampliação ocupa o espaço restante.

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

• As colunas com auto se posicionarão para fornecer um espaço amplo para o conteúdo a ser renderizado.
• No caso de Exibições de imagem, as imagens serão reduzidas para se ajustarem à largura restante.
• Observação: as imagens serão reduzidas apenas para os tamanhos de imagem stretch e auto, mas não para largura e altura fixas em pixels.

weights versus pixels

1. Colunas com combinação de larguras 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 pelo pixel value
• A largura das colunas 1 e 3 é ajustada com base no weights e no weight ratio calculado.

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 50 e Column4: auto
• Observação: a exibição de imagem com a coluna de largura auto é reduzida 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 por diferentes combinações de altura para elementos de cartão

1. Os elementos se expandem livremente na vertical quando o cartão não tem altura fixa

• Ambas as colunas podem ser expandidas suficientemente na vertical, independentemente dos valores auto e stretch
• Isso ocorre com a propriedade wrap desabilitada para o bloco de texto.

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

Espaçamento e Separador

1. A propriedade spacing em cada elemento influencia a quantidade de espaço entre o elemento ATUAL e o ANTERIOR a ele.
2. O espaçamento SÓ PODE ser aplicado quando há realmente um elemento que o precede. (Por exemplo, não será aplicado ao primeiro item em uma matriz)
3. Um renderizador PRECISA pesquisar a quantidade de espaço a ser usada do espaçamento hostConfig para o valor de enumeração aplicado ao elemento atual.
4. Se o elemento tiver um valor de separator igual a true, uma linha visível PRECISARÁ ser desenhada entre o elemento atual e a anterior.
5. A linha do separador PRECISA ser desenhada usando o container.style.default.foregroundColor.
6. Um separador SÓ PODERÁ ser desenhado se o item NÃO FOR o primeiro na matriz.
7. Espaçamento: os valores permitidos são none, small, default, medium, large, extra large e padding

• O atributo Espaçamento adiciona espaçamento entre o elemento em questão e o elemento anterior.

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

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

2. Separador: valores possíveis (alternância entre ativar/desativar)

• Desenha uma linha divisora na parte superior do elemento.

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

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

• A distância de espaçamento geral é mantida em relação aos valores fornecidos.
• O separador é adicionado na metade da distância do espaço.

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

Estilos de Contêiner

• Fornece dicas de estilo para contêineres como columns e columnset
• 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 a cor da tela de fundo

1. O cartão A ilustra columns e columnset sem nenhuma opção de estilo
2. O cartão B ilustra o columnset com o estilo Atenção. Observe o preenchimento dentro do contêiner columnset e a alteração na cor da tela de fundo.
3. O cartão C ilustra columns apenas com aplicação de estilo. Semelhante ao anterior, a coluna inclui alterações de preenchimento e de tela de fundo.
4. O cartão D ilustra columns e columnset, ambos com opções de estilo.

[Observação. É necessário verificar como o valor de preenchimento é determinado. Ele é determinado pelo host? ]

Sangria

• Essa propriedade permite que o contêiner, como columns e columnset, seja sangrado através do respectivo pai.
• Valores possíveis: on e off.

1. O cartão A ilustra columns e columnset com estilo normal.
2. O cartão B ilustra a primeira coluna com a opção de sangria. O conteúdo apenas sangra pelos próprios limites para aqueles do respectivo pai.

Tamanho da imagem

Atributo Size

• Valores permitidos: auto, stretch, small, medium e large
• auto : As imagens serão reduzidas para caber, se necessário, mas não serão dimensionadas para preencher a área.
• stretch : Imagem com redução e aumento para caber conforme necessário.
• smalle medium large: A imagem é exibida com uma largura fixa, onde a largura é determinada pelo host.

1. auto versus stretch

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

• Geralmente, colunas com a largura stretch permitem que as imagens sejam escalonadas livremente com o tamanho stretch.
• Colunas com a largura auto permitem que a imagem ocupe um espaço exato independentemente de tamanho da imagem auto e stretch.
• A largura da coluna tem mais precedência para a determinação do tamanho da imagem nessa disposição.

Atributo Width (in pixels) da imagem

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

• A coluna com a largura auto terá mais precedência do que stretch no fornecimento de espaço para conteúdo de imagem nessa disposição.

Combinação de Largura da Coluna (weight e pixel) e Tamanho da imagem (auto e stretch)

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

Resumo do layout avançado

• A Largura da coluna tem precedência para determinação do tamanho da imagem sobre o tamanho dessa imagem (auto, stretch, min width etc).
• A precedência da largura da coluna usada para exibir o conteúdo dela de maneira suficiente: px>weight>auto>stretch
• O size da imagem (auto, stretch) é ignorado quando width e height da imagem em px são fornecidos.
• O atributo de tamanho stretch da imagem aumentará a imagem somente quando houver espaço restante e a largura da coluna não for auto.
• Uma imagem é aumentada até o limite em que ela mantém a própria taxa de proporção no espaço disponível na coluna. Por sua vez, a altura se expande livremente.
• O atributo Spacing não terá nenhum efeito quando esse for o primeiro ou o único elemento entre os irmãos dele.

Ações

1. Se HostConfig supportsInteractivity for false, um renderizador NÃO PODERÁ renderizar nenhuma ação.
2. A propriedade actionsPRECISA 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 PRECISA permitir que o aplicativo host manipule o evento.
4. O evento PRECISA passar todas as propriedades associadas com a ação
5. O evento PRECISA passar adiante o AdaptiveCard que foi executado

Ação	Comportamento
Action.OpenUrl	Abre uma URL externa para exibição
Action.ShowCard	Solicita que um subcartão a ser mostrado ao usuário.
Action.Submit	Solicita que todos os elementos de entrada sejam reunidos em um objeto que é então enviado para você por meio de um método definido pelo aplicativo host.
Ação.Executar	(Introduzido na v1.4) Solicita que todos os elementos de entrada sejam reunidos em um objeto que é enviado para você por meio de um "pipeline de ação universal".

Action.OpenUrl

1. O Action.OpenUrl DEVE abrir uma URL usando o mecanismo da plataforma nativa
2. Se isso não for possível, ele PRECISARÁ acionar um evento para o aplicativo host para lidar com a abertura da URL. Esse evento PRECISA permitir que o aplicativo host substitua o comportamento padrão. Por exemplo, deixe que eles abram a URL no próprio aplicativo deles.

Action.ShowCard

1. O Action.ShowCard PRECISA ser compatível de algum modo, com base na configuração hostConfig. Há dois modos: embutido e popup. Os cartões embutidos DEVEM alternar automaticamente a visibilidade do cartão. No modo pop-up, um evento DEVE ser acionado para o aplicativo host para mostrar o cartão de alguma forma.

Action.Submit

• O elemento Action.Submit reúne campos de entrada, mescla-se com o campo de dados opcional e envia um evento para o cliente.
• Há uma diferença significativa no comportamento do elemento entre as versões 1.x e 2.x do renderizador de ACL.

A ação Submit se comporta como um envio de formulário HTML, com exceção de que, quando o HTML dispara um HTTP POST, os Cartões Adaptáveis deixam a cargo de cada aplicativo host determinar o que significa "submit".

1. Quando isso PRECISA acionar um evento, o usuário toca a ação invocada.
2. A propriedade dataPRECISA ser incluída no conteúdo do retorno de chamada.
3. Para Action.Submit, um renderizador PRECISA reunir todas as entradas no cartão e recuperar os valores delas.

• 1.x Renderer: as entradas são coletadas de todos os campos, independentemente do local na hierarquia em que o campo de entrada está presente.
• 2.x Renderer: as entradas são coletadas de campos presentes no contêiner pai ou como um irmão do elemento Action.Submit.

Action.Execute (os detalhes serão fornecidos posteriormente)

Action.Execute foi introduzido na versão 1.4. Forneceremos diretrizes de implementação para os SDKs posteriormente. Entre em contato caso tenha dúvidas sobre este tópico.

selectAction

1. Se o Host Config supportedInteractivity for false, um selectAction NÃO PODERÁ ser renderizado como um destino de toque.
2. Image, ColumnSet e Column oferecem uma propriedade selectAction, que DEVE ser executada quando o usuário a chama, por exemplo, tocando no elemento.

Entradas

1. Se o HostConfig supportsInteractivity for false, um renderizador NÃO PODERÁ renderizar nenhuma entrada.
2. As entradas DEVEM ser renderizadas com a maior fidelidade possível. Por exemplo, uma Input.Date idealmente ofereceria um seletor de data a um usuário, mas se isso não for possível em sua pilha de interface do usuário, o renderizador PRECISARÁ realizar fallback para renderizar uma caixa de texto padrão.
3. Um renderizador DEVE exibir o placeholderText se possível
4. A associação de valor de entrada PRECISA ter um escape adequado
5. Antes da v1.3, um renderizador NÃO precisa implementar a validação da entrada. Os usuários de Cartões Adaptáveis precisam planejar a validação de todos os dados recebidos por eles.
6. Rótulos de entrada e Validação foram introduzidos na v1.3 do Esquema dos Cartões Adaptáveis. É necessário ter ainda mais cuidado ao renderizar o rótulo, as dicas de validação e as mensagens de erro associados.

APIs de Estilo, Personalização e Extensibilidade

Cada SDK deve fornecer um determinado nível de flexibilidade para hospedar aplicativos, a fim de controlar o estilo geral e estender o esquema conforme adequado.

Configuração do host

• TODO: Quais devem ser os padrões? Todos eles devem compartilhá-lo? Devemos inserir um arquivo 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 as propriedades independentes de plataforma sejam compartilhadas entre os renderizadores em diferentes plataformas e dispositivos. Isso também permite que as ferramentas sejam criadas, o que lhe dá uma ideia da aparência que o cartão teria em um determinado ambiente.

1. Os renderizadores PRECISAM expor um parâmetro Host Config para hospedar aplicativos
2. Todos os elementos PRECISAM ser estilizados de acordo com as respectivas configurações de HostConfig

Estilo de plataforma nativa

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

Extensibilidade

1. Um renderizador PRECISA permitir que aplicativos host substituam renderizadores de elemento padrão. Por exemplo, que esses aplicativos substituam a renderização de TextBlock pela própria lógica deles.
2. Um renderizador PRECISA permitir que aplicativos host registrem tipos de elemento personalizados. Por exemplo, adicionar suporte para um elemento Rating personalizado
3. Um renderizador PRECISA permitir que aplicativos host removam o suporte para um elemento padrão. Por exemplo, remova Action.Submit se eles não quiserem que ele seja compatível.

Eventos

1. Um renderizador DEVERÁ disparar um evento quando a visibilidade de um elemento tiver sido alterada, permitindo que o aplicativo host faça a rolagem do cartão para a posição correta.