Cómo crear tarjetas interactivas

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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 el complemento necesita o proporcionar otros controles de interacción.

Cómo agregar acciones a los widgets

En general, los widgets deben ser interactivos si los vinculas a acciones específicas y si implementas 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 a fin de que realice una acción específica cuando se selecciona o se actualiza:

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

Ejemplo

En el siguiente ejemplo, se configura 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 muestra un elemento 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)
            .setType(CardService.NotificationType.INFO))
        .build();      // Don't forget to build the response!
  }

Diseñe 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 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 necesitas compilar la URL primero o realizar otros pasos adicionales 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 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.

  • Usa funciones de devolución de llamada simples. Para mantener la receptividad de los complementos, el servicio de tarjeta 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 al Action.

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