Cómo crear tarjetas interactivas

La mayoría de los complementos, además de presentar datos, requieren que el usuario ingrese información. Cuando compilas un complemento basado en tarjetas, puedes usar widgets interactivos, como botones, elementos del menú de la barra de herramientas o casillas de verificación para solicitar al usuario los datos que necesita el complemento o proporcionar otros controles de interacción.

Cómo agregar acciones a los widgets

En general, para que los widgets sean interactivos, los vinculas a acciones específicas y, luego, implementas el comportamiento requerido en una función de devolución de llamada. Consulta las acciones de los complementos para obtener más detalles.

En la mayoría de los casos, puedes seguir este procedimiento general para configurar un widget de modo que realice una acción específica cuando se seleccione o se actualice:

  1. Crea un objeto Action y especifica la función de devolución de llamada que se debe ejecutar, junto con los parámetros obligatorios.
  2. Vincula el widget a Action llamando a la función del controlador de widgets adecuada.
  3. Implementa la función de devolución de llamada para implementar el comportamiento requerido.

Ejemplo

En el siguiente ejemplo, se configura un botón que muestra una notificación del usuario después de que se hace clic en él. El clic activa la función de devolución de llamada notifyUser() con un argumento que especifica el texto de la notificación. Si se muestra una ActionResponse compilada, se generará una notificación.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText)
        .build();      // Don't forget to build the response!
  }

Diseña interacciones efectivas

Cuando diseñes tarjetas interactivas, ten en cuenta lo siguiente:

  • Por lo general, los widgets interactivos necesitan al menos un método de controlador para definir su comportamiento.

  • Usa la función de controlador de widgets setOpenLink() cuando tengas una URL y solo quieras abrirla en una pestaña. Esto evita la necesidad de definir un objeto Action y una función de devolución de llamada. Si primero necesitas compilar la URL o realizar cualquier otro paso adicional antes de abrirla, define un Action y usa setOnClickOpenLinkAction() en su lugar.

  • Cuando usas las funciones del controlador de widgets setOpenLink() o setOnClickOpenLinkAction(), debes proporcionar un objeto OpenLink para definir la URL que se abrirá. También puedes usar este objeto para especificar el comportamiento de apertura y cierre mediante las enumeraciones OpenAs y OnClose.

  • Es posible que más de un widget use el mismo objeto Action. Sin embargo, debes definir diferentes objetos Action si quieres proporcionar parámetros diferentes a la función de devolución de llamada.

  • Mantén las funciones de devolución de llamada simples. Para que los complementos sigan siendo responsivos, el servicio de tarjetas limita las funciones de devolución de llamada a un máximo de 30 segundos de tiempo de ejecución. Si la ejecución lleva más tiempo, es posible que la IU del complemento no actualice correctamente la visualización de la tarjeta en respuesta a Action .

  • Si el estado de los datos de un backend de terceros cambia como resultado de una interacción del usuario con la IU de tu complemento, se recomienda que el complemento establezca un bit de "estado cambiado" en true para que se borre cualquier caché existente del cliente. Consulta la descripción del método ActionResponseBuilder.setStateChanged() para obtener más detalles.