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

Para um widget do tipo Adaptive Card, defina a interface do usuário e as interações por meio de um modelo JSON de Cartões Adaptáveis e, opcionalmente, um payload de dados JSON separado. Este artigo orienta você por um modelo de widget de contagem com associação de dados e layout condicional. Windows widgets também podem exibir HTML de uma URL; para esse formato de conteúdo, consulte provedores de widget da Web.

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 Designer de Cartões Adaptáveis é uma ferramenta online para editar o JSON do cartão e visualizar seu layout e associação de dados. Abra o Designer para trabalhar no modelo.

Importante

O Designer usa seu próprio renderizador e opções de host. Não presuma que os recursos oferecidos por ele sejam suportados pelo Painel de Widgets, ou que ele forneça valores $host específicos do Windows. Esse passo a passo não depende de uma predefinição de host ou de um editor de dados de host. Teste o modelo final em um provedor de widgets do Windows para cada tema e tamanho com suporte.

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

Começar com um cartão em branco

O editor payload do cartão contém a definição JSON do cartão. Substitua seu conteúdo 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 obter informações sobre como associar esses dados ao modelo, consulte Cartões Adaptáveis Template Language.

Propriedades do host de widget do Windows

O Widgets Board fornece propriedades de host no runtime. Faça referência a eles por meio de $host em expressões de modelo, como ${$host.widgetSize}. Essas propriedades são separadas do conteúdo de dados do provedor; a adição de um campo widgetSize aos dados de exemplo não define $host.widgetSize.

Propriedade	Valor	Descrição
host.widgetSize	"pequeno", "médio" ou "grande"	O tamanho do widget fixado.
host.hostTheme	"claro" ou "escuro"	O tema atual do dispositivo no qual o Widgets Board é exibido.
host.isSettingsPayload	verdadeiro ou falso	Quando esse valor for verdadeiro, o usuário clicará no botão Personalizar widget no menu de contexto do widget. Você pode usar esse valor de propriedade para exibir elementos das configurações de personalização da interface do usuário. Esse é um método alternativo para usar IWidgetProvider2.OnCustomizationRequested para alterar o conteúdo JSON no aplicativo do provedor de widget. Para obter mais informações, consulte Implementando a personalização do widget.
host.isHeaderSupported	verdadeiro ou falso	Quando esse valor é verdadeiro, há suporte para personalização de cabeçalho. Para obter mais informações, consulte isHeaderSupported.
host.isHeader	verdadeiro ou falso	Quando esse valor é verdadeiro, o host está solicitando um payload especificamente para a renderização do cabeçalho do widget.
host.isWebSupported	verdadeiro ou falso	Quando esse valor é falso, o host atualmente não dá suporte ao carregamento do conteúdo da Web de um widget. Quando isso ocorrer, os widgets da Web exibirão a carga JSON de fallback fornecida pelo provedor de widget, mas esse valor pode ser usado para personalizar ainda mais o conteúdo. Para obter mais informações, consulte provedores de widget da Web
host.isUserContextAuthenticated	verdadeiro ou falso	Quando esse valor é falso, a única ação com suporte é Action.OpenUrl. O valor de isUserContextAuthenticated pode ser usado para ajustar o conteúdo do widget adequadamente, considerando as limitações de interatividade.

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

Adicione elementos TextBlock

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

Implementando o layout condicional

No editor de payload do Card, 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\"}"
    }
]

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 suportadas em Cartões Adaptáveis, consulte Layout condicional com $when.

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

Quando o Painel de Widgets avalia o modelo com $host.widgetSize definido como "small", somente o bloco de texto de tamanho pequeno aparece junto com a contagem:

Depois de integrar o modelo ao seu provedor, redimensione o widget fixado no Painel de Widgets e verifique se o bloco de texto correspondente é exibido. Declare cada tamanho que você deseja testar no manifesto do provedor de widget. Uma visualização genérica do Designer sem dados de host do Windows não pode verificar essas condições.

Associar ao contexto de dados

O exemplo usa uma propriedade de dados chamada count, referenciada por ${count} no primeiro TextBlock. Em runtime, o provedor envia a carga de dados para o host do widget. No momento do design, insira o seguinte JSON no editor de Dados de exemplo e habilite a visualização do Designer para verificar a vinculação de contagem. Esses dados de exemplo não fornecem as propriedades de host Windows separadas.

{"count": "2"}

Com {"count": "2"} como dados de exemplo, a expansão de modelo substitui ${count} por 2 no primeiro TextBlock. Verifique essa associação no Designer depois de habilitar a visualização. Verifique as condições específicas $host.widgetSize no Painel de Widgets, conforme descrito acima.

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

A propriedade type seleciona Action.Execute, que o host do widget encaminha para o callback OnActionInvoked. Em vez disso, use Action.OpenUrl para navegação de URL; ele não invoca esse retorno de chamada do provedor. O título fornece o texto do botão e o verbo é a operação definida pelo aplicativo que o provedor manipula. Quando $host.isUserContextAuthenticated for falso, não ofereça interações do tipo Action.Execute; apenas Action.OpenUrl é suportado.

O modelo de widget completo

A listagem de código a seguir mostra o modelo final para a interação counting-widget. O botão Action.Execute requer um contexto de usuário autenticado. Valide-o no Painel de Widgets com seu provedor; O Designer não executa o manipulador de incremento do provedor.

{
    "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 payload 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.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"
}