Criar um modelo de widget com o Designer de Cartões Adaptáveis

A interface do usuário e a interação para widgets Windows são implementados usando Cartões Adaptáveis. Cada widget fornece um modelo visual e, opcionalmente, um modelo de dados definido usando documentos JSON que estão em conformidade com o esquema Cartões Adaptáveis. 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 widget 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 diretrizes 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 Cartões Adaptáveis Designer é uma ferramenta interativa online que facilita a geração de modelos JSON para Cartões Adaptáveis. Usando o designer, você pode ver os visuais renderizados e o comportamento de associação de dados em tempo real à medida que cria seu modelo de widget. Siga o link para abrir o designer, que será usado para todas as etapas neste passo a passo.

Criar um modelo vazio com base em uma predefinição

Na parte superior da página, na lista suspensa Selecionar aplicativo host , escolha Widgets Board. Isso definirá o tamanho do contêiner para que o Cartão Adaptável tenha um tamanho com suporte para widgets. Observe que os widgets dão suporte a 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 transbordar as bordas, pois o substituiremos por conteúdo projetado para caber dentro do widget.

Há três editores de texto na parte inferior da página. O componente rotulado Editor de Payload de Cartão contém a definição JSON da interface de usuário do widget. O Editor de Dados de Exemplo contém um JSON que define um contexto de dados opcional para seu widget. O contexto de dados é associado dinamicamente ao Cartão Adaptável quando o widget é renderizado. Para obter mais informações sobre a associação de dados no Cartões Adaptáveis, consulte Cartões Adaptáveis Template Language.

O terceiro editor de texto é chamado Editor de Dados de Host de Exemplo. Observe que este editor pode ser recolhido para ficar abaixo dos outros dois editores da página. Nesse caso, clique em + para expandir o editor. Aplicativos de host de widget podem especificar propriedades do host que você pode usar em seu template de widget para exibir dinamicamente conteúdo diferente com base nos valores atuais das propriedades. O Widgets Board dá suporte às seguintes propriedades de host.

O tamanho do contêiner e o tema nas listas suspensas ao lado do menu suspenso de seleção de aplicativo host na parte superior da página permitem a configuração dessas propriedades sem a necessidade de editar manualmente o arquivo 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 observará que o documento JSON no editor de dados de exemplo está vazio.

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

Adicione elementos TextBlock

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

Implementando o layout condicional

O Editor de Conteúdo de Cartão foi atualizado para refletir os elementos TextBlock que adicionamos. Substitua a cadeia de caracteres JSON para o objeto body 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\"}"
    }
]

No Cartões Adaptáveis Template Language, a propriedade $when especifica que o elemento contido é exibido quando o valor associado é avaliado como verdadeiro. Se o valor for avaliado como false, o elemento que contém não será exibido. No elemento body em nosso exemplo, um dos três elementos TextBlock será mostrado e os outros dois ocultos, dependendo do valor da $host.widgetSize propriedade. Para obter mais informações sobre as condicionais com suporte no Cartões Adaptáveis, consulte Conditional layout com $when.

Agora, a visualização deve ser semelhante à seguinte imagem:

Observe que as instruções condicionais não estão sendo refletidas na 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 contêiner, selecione "Médio" e observe que a pré-visualização passa a mostrar somente o TextBlock para o tamanho médio. O contêiner na visualização também altera o tamanho, demonstrando como você pode usar a visualização para garantir que sua interface do usuário se ajuste ao contêiner de widget para cada tamanho com suporte.

Associar 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 do primeiro TextBlock inclui a referência de variável $count. Quando o widget está em execução no Widgets Board, o provedor de widget é responsável por montar o conteúdo de dados e passá-lo para o host do widget. Em tempo de design, você pode usar o Editor de Dados de Exemplo para protótipo do conteúdo de dados e ver como valores diferentes afetam a exibição do widget. Substitua a carga de dados vazia pelo JSON a seguir.

{"count": "2"}

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

Adicionar um botão

A próxima etapa é adicionar um botão ao nosso widget. No host do widget, quando o usuário clicar no botão, o host fará uma solicitação para o provedor de widget. Para este exemplo, o provedor de widget incrementará o valor de contagem e retornará uma carga de dados atualizada. Como essa operação requer um provedor de widget, você não poderá exibir esse comportamento no Designer de Cartões Adaptáveis, mas ainda poderá usar o designer para ajustar o layout do botão na interface do usuário.

Com Cartões Adaptáveis, elementos interativos são definidos com elementos action. Adicione o seguinte bloco de JSON diretamente após o elemento body no editor de conteúdo do cartão. Adicione 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 cadeia de caracteres JSON, a propriedade type especifica o tipo de ação que está sendo representada. Os widgets só dão suporte ao tipo de ação "Action.Execute". O título contém o texto exibido no botão da ação. A propriedade verb é uma string definida pelo aplicativo que o host do widget enviará ao provedor de widget para comunicar a intenção associada à ação. Um widget pode ter várias ações e o código do provedor de 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 do conteúdo 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 conteúdo de configurações

A listagem de código a seguir mostra um exemplo simples de um conteúdo 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"
}