Creación de una plantilla de widget con el Diseñador de Tarjetas adaptables

Para un widget de Adaptive Card, defina la interfaz de usuario y las interacciones con una plantilla JSON de Tarjetas adaptables y, opcionalmente, una carga de datos JSON independiente. Este artículo le guía a través de una plantilla de widget de recuento con enlace de datos y diseño condicional. Windows widgets también pueden mostrar HTML desde una dirección URL; para ese formato de contenido, consulte Proveedores de widgets web.

Un widget de recuento

El ejemplo de este artículo es un widget de recuento simple que muestra un valor entero y permite al usuario incrementar el valor haciendo clic en un botón en la interfaz de usuario del widget. En esta plantilla de ejemplo se usa el enlace de datos para actualizar automáticamente la interfaz de usuario en función del contexto de datos.

Las aplicaciones deben implementar un proveedor de widgets para generar y actualizar la plantilla de widget o los datos y pasarlos al host del widget. El artículo Implementación de un proveedor de widgets en una aplicación win32 proporciona instrucciones paso a paso para implementar el proveedor de widgets para el widget de recuento que generaremos en los pasos siguientes.

El Diseñador de Tarjetas adaptables

El Tarjetas adaptables Designer es una herramienta en línea para editar JSON de tarjeta y obtener una vista previa de su diseño y enlace de datos. Abra el Diseñador para trabajar en la plantilla.

Las imágenes siguientes muestran el diseño de la tarjeta, no la interfaz actual de Designer.

Empieza con una tarjeta en blanco

El editor de payload de la tarjeta contiene la definición JSON de la tarjeta. Sustituya el contenido por esta tarjeta en blanco:

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

El editor de datos de ejemplo contiene un contexto de datos JSON opcional. Para obtener información sobre cómo enlazar esos datos a la plantilla, consulte Tarjetas adaptables Template Language.

propiedades del host del widget de Windows

El panel widgets proporciona propiedades de host en tiempo de ejecución. Haga referencia a ellas mediante $host en expresiones de plantilla, como ${$host.widgetSize}. Estas propiedades son independientes de la carga de datos del proveedor; Agregar un widgetSize campo a los datos de ejemplo no establece $host.widgetSize.

El widget de recuento usa cuatro elementos TextBlock y una acción Action.Execute para su botón.

Agregar elementos TextBlock

Agregue cuatro elementos TextBlock desde la paleta de elementos del Diseñador o agréguelos directamente en el JSON de la tarjeta. Antes de aplicar el diseño condicional, la tarjeta tiene cuatro líneas de texto, como se muestra a continuación.

Implementación del diseño condicional

En el editor Carga útil de tarjeta, reemplace la matriz body por el fragmento siguiente:

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

En el lenguaje de plantilla de Tarjetas adaptables, la propiedad $when especifica que el elemento contenedor se muestra cuando el valor asociado se evalúa como true. Si el valor se evalúa como false, no se muestra el elemento contenedor. En el elemento body de nuestro ejemplo, se mostrará uno de los tres elementos TextBlock y los otros dos ocultos, dependiendo del valor de la $host.widgetSize propiedad. Para obtener más información sobre los condicionales admitidos en Tarjetas adaptables, vea Diseño condicional con $when.

Sin evaluar las expresiones de plantilla, la tarjeta muestra los cuatro bloques de texto:

Cuando el Panel de widgets evalúa la plantilla con establecida "small"en $host.widgetSize , solo aparece el bloque de texto de tamaño pequeño junto con el recuento:

Una tarjeta adaptable en curso. Muestra un widget con dos líneas que contienen el texto especificado en la carga JSON. Solo se representa el bloque de texto para el tamaño pequeño.

Después de integrar la plantilla con su proveedor, cambie el tamaño del widget anclado en el Panel de widgets y compruebe que aparece el bloque de texto coincidente. Declara cada tamaño que quiera probar en el manifiesto del proveedor de widgets. Una vista previa genérica del Diseñador sin datos de host de Windows no puede comprobar estas condiciones.

Enlazar al contexto de datos

En el ejemplo se usa una propiedad de datos denominada count, a la que hace ${count} referencia en el primer TextBlock. En tiempo de ejecución, el proveedor envía la carga de datos al host del widget. En tiempo de diseño, escriba el siguiente JSON en el editor de datos de ejemplo y habilite la vista previa del Diseñador para comprobar el enlace de recuento. Estos datos de ejemplo no proporcionan las propiedades separadas del host de Windows.

{"count": "2"}

Con {"count": "2"} como datos de ejemplo, la expansión de plantillas reemplaza ${count} por 2 en el primer TextBlock. Compruebe este enlace en el Diseñador después de habilitar la vista previa. Compruebe las condiciones $host.widgetSize por separado en Panel de widgets, como se ha descrito anteriormente.

Adición de un botón

El siguiente paso es agregar un botón a nuestro widget. En el host del widget, cuando el usuario hace clic en el botón, el host realizará una solicitud al proveedor del widget. En este ejemplo, el proveedor de widgets incrementará el valor de recuento y devolverá una carga de datos actualizada. Dado que esta operación requiere un proveedor de widgets, no podrá ver este comportamiento en el Diseñador de Tarjetas adaptables, pero todavía puede usar el diseñador para ajustar el diseño del botón dentro de la interfaz de usuario.

Con Tarjetas adaptables, los elementos interactivos se definen con elementos action. Agregue el siguiente bloque de JSON directamente después del elemento body en el editor de carga de tarjeta. Asegúrese de agregar una coma después del corchete de cierre (]) del elemento body o el diseñador notificará un error de formato.

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

La propiedad type selecciona Action.Execute, que el host del widget reenvía a la devolución de llamada OnActionInvoked del proveedor. Utilice Action.OpenUrl para la navegación URL en su lugar; no invoca ese callback del proveedor. El title proporciona el texto del botón y verb es la operación definida por la aplicación que gestiona el proveedor. Cuando $host.isUserContextAuthenticated es false, no ofrezca interacciones Action.Execute ; solo se admite Action.OpenUrl .

Plantilla de widget completa

En la lista de código siguiente se muestra la plantilla final para la interacción del widget de recuento. Su botón Action.Execute requiere un contexto de usuario autenticado. Valídelo en Panel de widgets con su proveedor; el Diseñador no ejecuta el controlador de incremento de su proveedor.

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

Ejemplo de carga útil de configuración

En la lista de código siguiente se muestra un ejemplo sencillo de una carga JSON que usa la propiedad host.isSettingsPayload para mostrar contenido diferente cuando el usuario ha clic en el botón 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"
}