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 de menú de la barra de herramientas o casillas de verificación, para solicitarle al usuario los datos que necesita tu complemento o proporcionar otros controles de interacción.

Cómo agregar acciones a los widgets

En su mayor parte, los widgets se vuelven interactivos cuando se vinculan a acciones específicas y se implementa el comportamiento requerido en una función de devolución de llamada. Consulta acciones de 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 lo selecciona o actualiza:

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

Ejemplo

En el siguiente ejemplo, se establece un botón que muestra una notificación del usuario después de hacer 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 devuelve un objeto ActionResponse compilado, se muestra 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 eficaces

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 del widget 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 otros pasos adicionales antes de abrirla, define un Action y usa setOnClickOpenLinkAction() en su lugar.

  • Cuando usas las funciones de controlador de widgets setOpenLink() o setOnClickOpenLinkAction(), debes proporcionar un objeto OpenLink para definir qué URL abrir. También puedes usar este objeto para especificar el comportamiento de apertura y cierre con 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 deseas proporcionar diferentes parámetros a la función de devolución de llamada.

  • Mantén simples tus funciones de devolución de llamada. Para que los complementos sigan respondiendo, 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 tarda más, 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 en un backend de terceros cambia como resultado de una interacción del usuario con la IU del complemento, se recomienda que el complemento establezca un bit de "cambio de estado" 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.