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

Para um widget de Adaptive Card, defina a interface e as interações com um template JSON de Cartões Adaptativos e, opcionalmente, uma carga útil de dados JSON separada. Este artigo guia-o através de um modelo de widget de contagem com ligação de dados e layout condicional. Os widgets do Windows também podem mostrar HTML a partir de uma URL; para esse formato de conteúdo, veja Fornecedores de widgets Web.

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 online para editar JSON de cartões e pré-visualizar o seu layout e ligação de dados. Abre o Designer para trabalhar no modelo.

Importante

O Designer utiliza o seu próprio renderizador e opções de host. Não presuma que as funcionalidades por ele disponibilizadas são suportadas pelo Widgets Board, ou que fornece valores específicos $host do Windows. Este guia não depende de uma predefinição de host nem de um editor de host-data. Teste o modelo final num fornecedor de widgets do Windows para cada tamanho e tema suportados.

As imagens abaixo ilustram o layout do cartão, não a interface atual do Designer.

Comece com um cartão em branco

O editor payload do cartão contém a definição JSON do cartão. Substitua os seus conteúdos por este cartão em branco:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

O editor de dados de exemplo contém um contexto de dados JSON opcional. Para informações sobre como vincular esses dados ao template, consulte Cartões Adaptativos Template Language.

Propriedades do anfitrião de widgets do Windows

O Widgets Board fornece propriedades do anfitrião em tempo de execução. Refira-se a eles através de $host em expressões de modelo, como ${$host.widgetSize}. Estas propriedades são separadas da carga útil de dados do seu fornecedor; adicionar um widgetSize campo aos dados da amostra não define $host.widgetSize.

Propriedade	Value	Descrição
host.widgetSize	"pequeno", "médio" ou "grande"	O tamanho do widget fixado.
host.hostTheme	"claro" ou "escuro"	O tema atual do dispositivo onde o Quadro de Widgets é exibido.
host.isSettingsPayload	verdadeiro ou falso	Quando este valor é verdadeiro, o utilizador clica no botão Personalizar widget no menu de contexto do widget. Pode usar este valor de propriedade para mostrar elementos da interface de utilizador (UI) para a personalização das definições. Este é um método alternativo ao uso do IWidgetProvider2.OnCustomizationSolicitado para alterar o payload JSON na aplicação do fornecedor de widgets. Para mais informações, consulte Implementação da personalização de widgets.
host.isHeaderSupported	verdadeiro ou falso	Quando este valor é verdadeiro, é suportada a personalização do cabeçalho. Para mais informações, consulte isHeaderSupported.
host.isHeader	verdadeiro ou falso	Quando este valor é verdadeiro, o host está a pedir uma carga útil especificamente para renderização do cabeçalho do widget.
host.isWebSupported	verdadeiro ou falso	Quando este valor é falso, o host não suporta atualmente o carregamento do conteúdo web de um widget. Quando isto acontece, os widgets web exibem o payload JSON de reserva fornecido pelo fornecedor de widgets, mas este valor pode ser usado para personalizar ainda mais o conteúdo. Para mais informações, consulte fornecedores de widgets Web
host.isUserContextAuthenticated	verdadeiro ou falso	Quando este valor é falso, a única ação suportada é Action.OpenUrl. O valor do isUserContextAuthenticated pode ser usado para ajustar o conteúdo dos widgets de forma adequada, dadas as limitações de interatividade.

O widget de contagem utiliza quatro elementos TextBlock e uma ação Action.Execute para o seu botão.

Adicionar elementos TextBlock

Adicione quatro elementos TextBlock da paleta de elementos do Designer, ou adicione-os diretamente no cartão JSON. Antes de ser aplicado o layout condicional, o cartão tem quatro linhas de texto, como ilustrado abaixo.

Implementação do layout condicional

No editor Carga útil do cartão, substitua o array body pelo seguinte fragmento:

"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.

Sem avaliar as expressões do modelo, o cartão mostra os quatro blocos de texto:

Quando o Widgets Board avalia o modelo com $host.widgetSize definido para "small", apenas o bloco de texto de pequeno tamanho aparece ao lado da contagem:

Depois de integrar o modelo com o seu fornecedor, redimensione o widget fixado no Quadro de Widgets e verifique se o bloco de texto correspondente aparece. Declara cada tamanho que queres testar no manifest do fornecedor de widgets. Uma pré-visualização genérica do Designer sem dados do host do Windows não pode verificar estas condições.

Vincular ao contexto dos dados

O exemplo utiliza uma propriedade de dados chamada count, referenciada por ${count} no primeiro TextBlock. Em tempo de execução, o provedor envia a carga útil de dados para o anfitrião do widget. No momento do design, introduza o JSON seguinte no editor de dados de exemplo e ative a pré-visualização no Designer para verificar a ligação de contagem. Estes dados de exemplo não fornecem as propriedades separadas do host do Windows.

{"count": "2"}

Com {"count": "2"} como dados de exemplo, a expansão do modelo substitui ${count} por 2 no primeiro TextBlock. Verifique esta ligação no Designer depois de ativar a pré-visualização. Verifique as condições separadas $host.widgetSize no Quadro de Widgets, conforme descrito acima.

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"                                           
    }                                                               
]

A propriedade type seleciona Action.Execute, que o host do widget encaminha para o callback OnActionInvoked do seu provedor. Utilize Action.OpenUrl para navegação por URL em vez disso; não invoca a chamada de retorno desse fornecedor. O título fornece o texto do botão, e o verbo é a operação definida pela aplicação que o fornecedor gere. Quando $host.isUserContextAuthenticated for falso, não ofereça Action.Execute interações; apenas Action.OpenUrl é suportado.

O modelo completo do widget

A seguinte listagem de código mostra o modelo final para a interação do counting-widget. O seu botão Action.Execute requer um contexto de utilizador autenticado. Valida-o no Quadro de Widgets com o teu provider; o Designer não executa o handler de incrementos do teu provider.

{
    "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.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}