Crie um modelo de widget com o Cartões Adaptativos Designer

A interface e a interação para Windows Widgets são implementadas usando Cartões Adaptativos. Cada widget fornece um modelo visual e, opcionalmente, um modelo de dados que são definidos usando documentos JSON que cumprem o esquema Cartões Adaptativos. Este artigo orienta-o pelos passos para criar um modelo simples de widget.

Um widget de contagem

O exemplo neste artigo é um widget simples de contagem que mostra um valor inteiro e permite ao utilizador incrementar esse valor clicando num botão na interface do widget. Este modelo de exemplo utiliza ligação de dados para atualizar automaticamente a interface com base no contexto dos dados.

As aplicações precisam de implementar um fornecedor de widgets para gerar e atualizar o modelo e/ou dados do widget e passá-los para o host do widget. O artigo Implementar um fornecedor de widgets numa aplicação win32 fornece orientações passo a passo para implementar o fornecedor de widgets para o widget de contagem que iremos gerar nos passos abaixo.

O Cartões Adaptativos Designer

O Cartões Adaptativos Designer é uma ferramenta interativa online que facilita a geração de templates JSON para Cartões Adaptativos. Usando o designer, pode ver os visuais renderizados e o comportamento de ligação de dados em tempo real enquanto constrói o seu modelo de widget. Siga a hiperligação para abrir o designer, que será usado para todas as etapas deste guia.

Criar um modelo vazio a partir de um preset

No topo da página, no menu suspenso Selecionar aplicação anfitriã , escolha Quadro de Widgets. Isto vai definir o tamanho do contentor para o Cartão Adaptativo para ter um tamanho compatível com widgets. Note que os widgets suportam tamanhos pequenos, médios e grandes. O tamanho do modelo predefinido é o tamanho correto para um widget pequeno. Não te preocupes se o conteúdo ultrapassar as bordas porque vamos substituí-lo por conteúdo desenhado para caber dentro do widget.

Existem três editores de texto no final da página. O que se chama Card Payload Editor contém a definição JSON da interface do seu widget. O editor denominado Editor de Dados de Exemplo contém JSON que define um contexto de dados opcional para o seu widget. O contexto de dados é vinculado dinamicamente ao Cartão Adaptativo quando o widget é renderizado. Para mais informações sobre ligação de dados em Cartões Adaptativos, consulte Cartões Adaptativos Template Language.

O terceiro editor de texto é denominado Sample Host Data Editor (Editor de Dados de Anfitrião de Exemplo). Note que este editor pode colapsar abaixo dos outros dois editores da página. Clique no sinal de + para expandir o editor. As aplicações anfitriãs de widgets podem especificar propriedades de anfitrião que pode usar no seu modelo de widget para exibir dinamicamente diferentes conteúdos com base nos valores atuais das propriedades. O Quadro de Widgets suporta as seguintes propriedades do hospedeiro.

Os menus suspensos Tamanho do Container e Tema ao lado do menu suspenso Selecione o aplicativo host no topo da página permitem definir estas propriedades sem editar manualmente o JSON de amostra do aplicativo host no editor.

Criar um novo cartão

No canto superior esquerdo da página, clique em Novo cartão. No diálogo Criação, selecione Cartão em Branco. Agora deves ver um Cartão Adaptativo vazio. 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 Cartão à esquerda da página para o cartão adaptativo em branco no painel de pré-visualização. Neste ponto, a pré-visualização do widget deverá assemelhar-se à imagem seguinte. O conteúdo volta a transbordar para além das fronteiras do widget, mas isso será corrigido nos passos seguintes.

Implementação do layout condicional

O Card Payload Editor foi atualizado para refletir os elementos TextBlock que adicionámos. Substitua a string JSON do objeto 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 Cartões Adaptativos Template Language, a propriedade $when especifica que o elemento contendo é exibido quando o valor associado é avaliado como verdadeiro. Se o valor for avaliado como falso, o elemento que contém não é apresentado. No elemento corpo do nosso exemplo, um dos três elementos TextBlock será mostrado, e os outros dois ocultos, dependendo do valor da $host.widgetSize propriedade. Para mais informações sobre os condicionais suportados em Cartões Adaptativos, veja Layout condicional com $when.

Agora a pré-visualização deve parecer a seguinte imagem:

Note que as afirmações condicionais não estão a ser refletidas na pré-visualização. Isto acontece porque o designer não está a simular o comportamento do anfitrião do widget. Clique no botão do modo Pré-visualização no topo da página para iniciar a simulação. A pré-visualização do widget agora parece a seguinte imagem:

No menu suspenso Tamanho do Contentor, selecione "Médio" e note que a pré-visualização muda para mostrar apenas o Bloco de Texto para o tamanho médio. O contentor na pré-visualização também muda de tamanho, demonstrando como pode usar a pré-visualização para garantir que a sua interface cabe dentro do contentor de widgets para cada tamanho suportado.

Vincular ao contexto dos dados

O nosso widget de exemplo usará uma propriedade de estado personalizada chamada "count". Pode ver no modelo atual que o valor para o TextBlock primeiro inclui a referência da variável $count. Quando o widget está a correr no Tabuleiro de Widgets, o fornecedor do widget é responsável por montar o payload de dados e passá-lo para o anfitrião do widget. No momento do design, pode usar o Editor de Dados de Exemplo para prototipar o seu payload de dados e ver como diferentes valores impactam a visualização do seu widget. Substitua a carga útil de dados vazia pelo seguinte JSON.

{"count": "2"}

Note que a pré-visualização agora insere o valor especificado para a propriedade count no texto do primeiro TextBlock.

Adicionar um botão

O passo seguinte é adicionar um botão ao nosso widget. No host do widget, quando o utilizador clica no botão, o host fará um pedido ao fornecedor do widget. Neste exemplo, o fornecedor de widgets irá incrementar o valor da contagem e devolver uma carga de dados atualizada. Como esta operação requer um fornecedor de widgets, não poderá visualizar este comportamento no Cartões Adaptativos Designer, mas ainda pode usar o designer para ajustar a disposição do seu botão dentro da sua interface.

Com Cartões Adaptativos, os elementos interativos são definidos com elementos de ação. Adicione o bloco seguinte 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 encerramento (]) do elemento do corpo, caso contrário o designer reportará um erro de formatação.

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

Nesta cadeia 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 que é exibido no botão da ação. A propriedade verbo é uma string definida pela aplicação que o anfitrião do widget enviará ao fornecedor do widget para comunicar a intenção associada à ação. Um widget pode ter múltiplas ações, e o código do fornecedor do widget verifica o valor do verbo no pedido para determinar que ação tomar.

O modelo completo do widget

A lista de código seguinte 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 pacote de definições

A seguinte listagem de código mostra um exemplo simples de uma carga útil JSON que utiliza a propriedade host.isSettingsPayload para mostrar conteúdos diferentes quando o utilizador 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"
}