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 pedirle al usuario los datos que necesita tu complemento o proporcionar otros controles de interacción.

Cómo agregar acciones a los widgets

En general, para hacer que los widgets sean interactivos, debes vincularlos a acciones específicas e implementar el comportamiento requerido en una función de devolución de llamada. Consulta las acciones de complementos para obtener más información.

En la mayoría de los casos, puedes seguir este procedimiento general para configurar un widget para que realice una acción específica cuando se seleccione o 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. Para vincular el widget a Action, llama 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 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 devuelves un ActionResponse compilado, se mostrará 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:

• Los widgets interactivos suelen necesitar 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 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 enums 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 proporcionarle diferentes parámetros a la función de devolución de llamada.

• Mantén las funciones de devolución de llamada simples. Para mantener la capacidad de respuesta de los complementos, 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 la tarjeta correctamente en respuesta a Action .

• Si un estado de 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 "estado cambiado" en true para que se borre cualquier caché del cliente existente. Consulta la descripción del método ActionResponseBuilder.setStateChanged() para obtener más detalles.