Cómo crear tarjetas interactivas

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

Cómo agregar acciones a los widgets

Para que los widgets sean interactivos, debes vincularlos a acciones específicas y, luego, implementar el comportamiento requerido en una 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 para realizar una acción específica cuando se seleccionan o actualizan:

1. Crea un objeto Action. la especificación de la función de devolución de llamada que se debe ejecutar, junto con cualquier los parámetros obligatorios.
2. Vincula el widget a Action llamando al Función del controlador del widget.
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 al usuario después de hacer clic en ella. El clic activa la función de devolución de llamada notifyUser(). con un argumento que especifique el texto de la notificación. Muestra una compilación ActionResponse 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 efectivas

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

• Generalmente, los widgets interactivos necesitan al menos un método de controlador para definir su de tu modelo.

• Usa el widget setOpenLink(). controlador cuando tienes una URL y solo quieres abrirla en una pestaña. Esto evita la necesidad de definir Objeto y devolución de llamada Action . Si necesitas crear la URL primero o tomar cualquier otra pasos antes de abrir la URL, define un Action y usa setOnClickOpenLinkAction() en su lugar.

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

• Es posible que más de un widget use el mismo Objeto Action. Sin embargo, debes definir diferentes Objetos Action si lo deseas para proporcionar diferentes parámetros 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 demora más tiempo, es posible que la IU del complemento no actualice la visualización de su tarjeta correctamente en respuesta al Action

• Si el estado de los datos en un backend de terceros cambia como resultado de la acción de un usuario interacción con la IU de tu complemento, se recomienda que el conjunto de complementos un “estado cambiado” bit a true para que cualquier caché existente del cliente se borrar. Consulta la ActionResponseBuilder.setStateChanged() descripción del método para obtener detalles adicionales.