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

La interfaz de usuario y la interacción para widgets de Windows se implementan mediante Tarjetas Adaptables. Cada widget proporciona una plantilla visual y, opcionalmente, una plantilla de datos que se define mediante documentos JSON que se ajustan al esquema de tarjetas adaptables. Este artículo le guía por los pasos para crear una plantilla de widget simple.

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.

Diseñador de tarjetas adaptables

El Diseñador de tarjetas adaptables es una herramienta interactiva en línea que facilita la generación de plantillas JSON para tarjetas adaptables. Con el diseñador, puede ver los objetos visuales representados y el comportamiento del enlace de datos en tiempo real a medida que compila la plantilla de widget. Siga el vínculo para abrir el diseñador, que se usará para todos los pasos de este tutorial.

Creación de una plantilla vacía a partir de un valor preestablecido

En la parte superior de la página, en la lista desplegable Seleccionar aplicación host, elija Panel de widgets. Esto establecerá el tamaño del contenedor para que la tarjeta adaptable tenga un tamaño compatible con los widgets. Tenga en cuenta que los widgets admiten tamaños pequeños, medianos y grandes. El tamaño del valor predeterminado de plantilla es el tamaño correcto para un widget pequeño. No se preocupe si el contenido desborda los bordes porque lo reemplazaremos por contenido diseñado para caber dentro del widget.

Hay tres editores de texto en la parte inferior de la página. La etiqueta Editor de carga de tarjeta contiene la definición JSON de la interfaz de usuario del widget. El editor con la etiqueta Sample Data Editor contiene JSON que define un contexto de datos opcional para el widget. El contexto de datos se enlaza dinámicamente a la tarjeta adaptable cuando se representa el widget. Para obtener más información sobre el enlace de datos en tarjetas adaptables, consulte lenguaje de plantilla de tarjetas adaptables.

El tercer editor de texto está etiquetado como Editor de datos de host de ejemplo. Tenga en cuenta que este editor puede colapsarse bajo los otros dos editores de la página. Si es así, haga clic en + para expandir el editor. Las aplicaciones de alojamiento de widgets pueden especificar propiedades del anfitrión que puede usar en la plantilla de widgets para mostrar dinámicamente contenido diferente según los valores actuales de las propiedades. El Panel de widgets admite las siguientes propiedades de host.

Las listas desplegables Tamaño del contenedor y Tema junto a la lista desplegable Seleccionar aplicación host en la parte superior de la página le permiten establecer estas propiedades sin editar manualmente el JSON del host de ejemplo en el editor.

Crear una nueva tarjeta

En la esquina superior izquierda de la página, haga clic en Nueva tarjeta. En el cuadro de diálogo Crear, seleccione Tarjeta En Blanco. Ahora debería ver una tarjeta adaptable vacía. También observará que el documento JSON del editor de datos de ejemplo está vacío.

El widget de recuento que crearemos es muy sencillo, solo consta de 4 elementos TextBlock y una acción de tipo Action.Execute, que define el botón del widget.

Agregar elementos TextBlock

Agregue cuatro elementos TextBlock arrastrándolos desde los elementos Tarjeta panel de la izquierda de la página a la tarjeta adaptable en blanco en el panel de vista previa. En este momento, la vista previa del widget debe ser similar a la siguiente imagen. El contenido vuelve a desbordarse fuera de los bordes del widget, pero esto se corregirá en los pasos siguientes.

Implementación del diseño condicional

El editor de carga de tarjeta se ha actualizado para reflejar los elementos TextBlock que agregamos. Reemplace la cadena JSON del objeto cuerpo por lo 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 $when propiedad 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 del cuerpo de nuestro ejemplo, se mostrará uno de los tres elementos TextBlock, y los otros dos estarán ocultos, según el valor de la propiedad $host.widgetSize. Para obtener más información sobre los condicionales admitidos en Adaptive Cards, consulte Diseño condicional con $when.

Ahora la versión preliminar debería tener un aspecto similar a la siguiente imagen:

Tenga en cuenta que las declaraciones condicionales no se reflejan en la versión preliminar. Esto se debe a que el diseñador no simula el comportamiento del host del widget. Haga clic en el botón de modo de vista previa en la parte superior de la página para iniciar la simulación. La vista previa del widget ahora es similar a la siguiente imagen:

En la lista desplegable de tamaño del contenedor , seleccione "Medium" y tenga en cuenta que la vista previa cambia para mostrar solo el TextBlock para el tamaño medio. El contenedor de la versión preliminar también cambia el tamaño, lo que muestra cómo puede usar la versión preliminar para asegurarse de que la interfaz de usuario se ajuste al contenedor de widgets para cada tamaño admitido.

Enlazar al contexto de datos

Nuestro widget de ejemplo usará una propiedad de estado personalizada denominada "count". Puede ver en la plantilla actual que el valor del primer TextBlock incluye la referencia de variable $count. Cuando el widget se ejecuta en el Panel de widgets, el proveedor de widgets es responsable de ensamblar la carga de datos y pasarlo al host del widget. En tiempo de diseño, puede usar el Editor de datos de ejemplo para crear prototipos de la carga de datos y ver cómo afectan los distintos valores a la visualización del widget. Reemplace la carga de datos vacía por el siguiente JSON.

{"count": "2"}

Tenga en cuenta que la vista previa ahora inserta el valor especificado para la propiedad count en el texto del primer TextBlock.

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 los elementos de acción . Agregue el siguiente bloque de JSON directamente después del elemento del cuerpo en el editor de carga útil de la 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"                                           
    }                                                               
]

En esta cadena JSON, la propiedad de tipo especifica el tipo de acción que se está representando. Los widgets solo admiten el tipo de acción "Action.Execute". El título contiene el texto que se muestra en el botón de la acción. La propiedad verbo es una cadena definida por la aplicación que el host del widget enviará al proveedor de widgets para comunicar la intención asociada a la acción. Un widget puede tener varias acciones y el código del proveedor del widget comprobará el valor del verbo en la solicitud para determinar qué acción realizar.

Plantilla de widget completa

En la lista de código siguiente se muestra la versión final de la carga 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"
    }
  ]
}

Ejemplo de carga 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.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"
}