La mayoría de los complementos requieren que el usuario ingrese información, además de presentar datos. 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 lograr que los widgets sean interactivos, debes vincularlos a acciones específicas y, luego, implementar 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 para que realice una acción específica cuando se selecciona o se actualiza:
- Crea un objeto
Action
y especifica la función de devolución de llamada que se debe ejecutar, junto con los parámetros requeridos. - Vincula el widget a
Action
llamando a la función de controlador del widget adecuada. - Implementa la función de devolución de llamada para ejecutar el comportamiento requerido.
Ejemplo
En el siguiente ejemplo, se configura un botón que muestra una notificación al 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 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 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 widget
setOpenLink()
cuando tengas una URL y solo quieras abrirla en una pestaña. Esto evita la necesidad de definir un objetoAction
y una función de devolución de llamada. Si necesitas compilar la URL primero o realizar otros pasos adicionales antes de abrir la URL, define unAction
y usasetOnClickOpenLinkAction()
en su lugar.Cuando usas las funciones del controlador del widget
setOpenLink()
osetOnClickOpenLinkAction()
, debes proporcionar un objetoOpenLink
para definir la URL que se abrirá. También puedes usar este objeto para especificar el comportamiento de apertura y cierre con las enumeracionesOpenAs
yOnClose
.Es posible que más de un widget use el mismo objeto
Action
. Sin embargo, debes definir diferentes objetosAction
si deseas proporcionar 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 de ese tiempo, es posible que la IU del complemento no actualice correctamente la visualización de tarjetas 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 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étodoActionResponseBuilder.setStateChanged()
para obtener detalles adicionales.