Criar um modelo de widget com o Adaptive Cards Designer

A interface do usuário e a interação para Widgets do Windows são implementadas usando Adaptive Cards. Cada widget fornece um modelo visual e, opcionalmente, um modelo de dados que são definidos usando documentos JSON que estão em conformidade com o esquema Adaptive Cards. Este artigo orienta você pelas etapas para criar um modelo de widget simples.

Um widget de contagem

O exemplo neste artigo é um widget de contagem simples que exibe um valor inteiro e permite que o usuário incremente o valor clicando em um botão na interface do usuário do widget. Este modelo de exemplo usa a associação de dados para atualizar automaticamente a interface do usuário com base no contexto de dados.

Os aplicativos precisam implementar um provedor de widgets para gerar e atualizar o modelo de widget e/ou dados e passá-los para o host do widget. O artigo Implementar um provedor de widget em um aplicativo win32 fornece orientação passo a passo para implementar o provedor de widget para o widget de contagem que geraremos nas etapas abaixo.

O Designer de Cartões Adaptáveis

O Adaptive Cards Designer é uma ferramenta interativa online que facilita a geração de modelos JSON para Adaptive Cards. Usando o designer, você pode ver os visuais renderizados e o comportamento de vinculação de dados em tempo real enquanto cria seu modelo de widget. Siga o link para abrir o designer, que será usado para todas as etapas deste passo a passo.

Criar um modelo vazio a partir de uma predefinição

Na parte superior da página, na lista suspensa Selecionar aplicação anfitriã, escolha Painel de Widgets. Isso definirá o tamanho do contêiner para o Adaptive Card para ter um tamanho compatível com widgets. Observe que os widgets suportam tamanhos pequenos, médios e grandes. O tamanho da predefinição de modelo padrão é o tamanho correto para um widget pequeno. Não se preocupe se o conteúdo ultrapassar as margens, porque vamos substituí-lo por conteúdo projetado para caber dentro do widget.

Há três editores de texto na parte inferior da página. O rotulado Editor de carga útil do cartão contém a definição JSON da interface do usuário do widget. O editor rotulado Sample Data Editor contém JSON que define um contexto de dados opcional para seu widget. O contexto de dados é vinculado dinamicamente ao Adaptive Card quando o widget é renderizado. Para obter mais informações sobre vinculação de dados em Adaptive Cards, consulte Adaptive Cards Template Language.

O terceiro editor de texto é rotulado Sample Host Data Editor. Note que este editor pode colapsar abaixo dos outros dois editores da página. Em caso afirmativo, clique no + para expandir o editor. As aplicações anfitriãs de widgets podem especificar propriedades anfitriãs que você pode usar no seu template de widget para exibir dinamicamente conteúdo diferente com base nos valores atuais das propriedades. O Widgets Board suporta as seguintes propriedades de host.

As listas suspensas Tamanho do contêiner e Tema ao lado da lista suspensa Selecionar aplicativo host na parte superior da página permitem que você defina essas propriedades sem editar manualmente o JSON do host de exemplo no editor.

Criar um novo cartão

No canto superior esquerdo da página, clique em Novo cartão. Na caixa de diálogo Criar , selecione Cartão em branco. Agora você deve ver um cartão adaptável vazio. Você também notará que o documento JSON no editor de dados de exemplo está vazio.

O widget de contagem que vamos criar é muito simples, consistindo apenas em 4 elementos TextBlock e uma ação do tipo Action.Execute, que define o botão do widget.

Adicionar elementos TextBlock

Adicione quatro elementos TextBlock arrastando-os do painel de elementos do Card à esquerda da página para o cartão adaptável em branco no painel de pré-visualização. Neste ponto, a visualização do widget deve assemelhar-se à imagem a seguir. O conteúdo novamente transborda fora das bordas do widget, mas isso será corrigido nas etapas a seguir.

Implementação de layout condicional

O Card Payload Editor foi atualizado para refletir os elementos TextBlock que adicionámos. Substitua a cadeia JSON do objeto do corpo pelo seguinte:

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

Na Linguagem de Modelo de Cartões Adaptáveis, a propriedade $when especifica que o elemento que contém é exibido quando o valor associado é avaliado como true. Se o valor for avaliado como false, o elemento que contém não será exibido. No elemento body no nosso exemplo, será mostrado um dos três elementos TextBlock e os outros dois ficarão ocultos, de acordo com o valor da propriedade $host.widgetSize. Para obter mais informações sobre as condicionais suportadas em cartões adaptáveis, consulte layout condicional com $when.

Agora, a pré-visualização deve assemelhar-se à imagem a seguir.

Observe que as declarações condicionais não estão a serem refletidas na pré-visualização. Isso ocorre porque o designer não está simulando o comportamento do host do widget. Clique no botão modo de visualização na parte superior da página para iniciar a simulação. A visualização do widget agora se parece com a seguinte imagem:

Na lista suspensa Tamanho do Contentor, selecione "Médio" e observe que a visualização alterna para mostrar apenas o Bloco de Texto para o tamanho médio. O contêiner na visualização também muda de tamanho, demonstrando como você pode usar a visualização para garantir que sua interface do usuário se encaixe dentro do contêiner de widget para cada tamanho suportado.

Vincular ao contexto de dados

Nosso widget de exemplo usará uma propriedade de estado personalizada chamada "count". Você pode ver no modelo atual que o valor para o primeiro TextBlock inclui a variável de referência $count. Quando o widget está sendo executado no Widgets Board, o provedor de widgets é responsável por montar a carga útil de dados e passá-la para o host do widget. Durante a fase de design, pode utilizar o Editor de dados de exemplo para prototipar a sua carga de dados e ver como valores diferentes afetam a exibição do seu widget. Substitua a carga de dados vazia pelo seguinte JSON.

{"count": "2"}

Observe que a visualização agora insere o valor especificado para a propriedade de contagem no texto do primeiro TextBlock .

Adicionar um botão

O próximo passo é adicionar um botão ao nosso widget. No host do widget, quando o usuário clica no botão, o host fará uma solicitação ao provedor do widget. Neste exemplo, o provedor de widgets incrementará o valor da contagem e retornará uma carga de dados atualizada. Como essa operação requer um provedor de widgets, você não poderá exibir esse comportamento no Adaptive Cards Designer, mas ainda poderá usar o designer para ajustar o layout do botão na interface do usuário.

Com os Cartões Adaptáveis, os elementos interativos são definidos com elementos de ação . Adicione o seguinte bloco de JSON diretamente após o elemento body no editor de payload do cartão. Certifique-se de adicionar uma vírgula após o colchete de fechamento (]) do elemento body ou o designer relatará um erro de formatação.

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

Nesta string JSON, a propriedade type especifica o tipo de ação que está a ser representada. Os widgets suportam apenas o tipo de ação "Action.Execute". O título contém o texto exibido no botão da ação. A propriedade verb é uma cadeia de caracteres definida pelo aplicativo que o host do widget enviará ao provedor do widget para comunicar a intenção associada à ação. Um widget pode ter várias ações, e o código do provedor do widget verificará o valor do verbo na solicitação para determinar qual ação tomar.

O modelo de widget completo

A listagem de código a seguir mostra a versão final da carga útil JSON.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

Exemplo de carga de dados de configurações

A listagem de código a seguir mostra um exemplo simples de uma carga JSON que usa a propriedade host.isSettingsPayload para exibir conteúdo diferente quando o usuário clica no botão Personalizar widget .

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
    "type": "Action.Submit",
    "title": "Increment",
    "verb": "inc",
    "$when": "${!$host.isSettingsPayload}"
    },
    {
    "type": "Action.Submit",
    "title": "Update Setting",
    "verb": "setting",
    "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}