Creación de una plantilla de widget con las tarjetas adaptables Designer

Nota

Parte de la información hace referencia al producto de versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

Importante

La característica descrita en este tema está disponible en las compilaciones preliminares de Dev Channel de Windows a partir de la compilación 25217. Para obtener información sobre las compilaciones en versión preliminar de Windows, consulte Windows 10 Insider Preview.

La interfaz de usuario y la interacción de los 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. En este artículo se describen los pasos necesarios para crear una plantilla de widget sencilla.

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

Las tarjetas adaptables Designer

Las tarjetas adaptables Designer 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 mientras 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 preestablecido de plantilla predeterminado 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 ajustarse dentro del widget.

Hay tres editores de texto en la parte inferior de la página. El editor de carga de tarjeta etiquetado contiene la definición JSON de la interfaz de usuario del widget. El editor con la etiqueta Editor de datos de ejemplo 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 tiene la etiqueta Editor de datos de host de ejemplo. Tenga en cuenta que este editor puede contraerse debajo de los otros dos editores de la página. Si es así, haga clic en + para expandir el editor. Las aplicaciones host de widget, como el Panel de widgets, tienen dos propiedades que indican el tamaño y el tema del widget. Estas propiedades se denominan host.widgetSize y host.hostTheme. Los tamaños admitidos son "pequeños", "medianos" y "grandes". Los temas admitidos son "claro" y "oscuro". La plantilla de widget puede mostrar dinámicamente contenido diferente en función del valor actual de estas propiedades. Para ver cómo responde el widget a los cambios en el tamaño y el tema, puede ajustar los valores de estas propiedades en el editor, o también puede establecer estos valores en 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.

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 el panel Elementos de tarjeta 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 body 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 body de nuestro ejemplo, se mostrará uno de los tres elementos TextBlock y los otros dos ocultos, según el valor de la $host.widgetSize propiedad. Para obtener más información sobre los condicionales admitidos en tarjetas adaptables, consulte Diseño condicional con $when.

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

Tenga en cuenta que las instrucciones 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 Modo de vista previa de 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 Tamaño del contenedor , seleccione "Medio" y observe que la vista previa cambia para mostrar solo 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 vista previa 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 $countde variable . Cuando el widget se ejecuta en el panel widgets, el proveedor del widget 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 Designer 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 de acción . Agregue el siguiente bloque de JSON directamente después del elemento body en el editor de carga 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 type 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"
    }
  ]
}