Acciones de complementos

Las acciones de complementos proporcionan comportamiento interactivo a los widgets. Cuando creas una acción, defines lo que sucede cuando el usuario selecciona o actualiza un widget.

En la mayoría de los casos, puedes definir acciones de complementos con objetos Action que proporciona el servicio de tarjetas de Google Apps Script. Cada Action se asocia con una función de devolución de llamada cuando la creas. Implementas la función de devolución de llamada para realizar los pasos seleccionados cuando el usuario interactúa con el widget. También debes vincular el Action al widget con una función de controlador de widgets adecuada que defina qué tipo de interacción activa la devolución de llamada de Action.

Configura un widget con un Action siguiendo este proceso:

  1. Crea el objeto Action, y especifica la función de devolución de llamada que debe ejecutar junto con los parámetros que requiera.
  2. Llama a la función de controlador de widgets adecuada en el widget con el objeto Action.
  3. Implementa la función de devolución de llamada para promulgar el comportamiento requerido.

No confundas los objetos Action con los objetos CardAction. Los objetos CardAction son elementos de menú del encabezado de la tarjeta, mientras que los objetos Action definen respuestas a las interacciones del usuario con la IU.

Funciones de controlador de widgets

Para vincular un widget a un Action o a otro comportamiento, usa una función de controlador de widgets. La función del controlador determina qué tipo de interacción (por ejemplo, hacer clic en el widget o editar un campo de texto) activa el comportamiento de la acción. La función de controlador también define qué pasos sigue la IU, si es que sigue alguno, después de que se completa la acción.

En la siguiente tabla, se enumeran los diferentes tipos de controladores para widgets y los widgets con los que se usan:

Función de controlador Activa la acción Widgets aplicables Descripción
setOnChangeAction El valor del widget cambia. DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		Establece un Action que ejecuta una función de Apps Script cuando el widget pierde el enfoque, como cuando el usuario ingresa texto en una entrada y presiona Intro. El controlador pasa automáticamente un objeto de evento a la función que llama. Puedes insertar información de parámetros adicionales en este objeto de evento si lo seleccionas.
setOnClickAction El usuario hace clic en el widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Establece un Action que ejecuta una función de Apps Script cuando el usuario hace clic en el widget. El controlador pasa automáticamente un objeto de evento a la función que llama. Puedes insertar información de parámetros opcionales en este objeto de evento.
setComposeAction El usuario hace clic en el widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Específico de Gmail. Establece un objeto Action que compila un borrador de correo electrónico y, luego, se lo presenta al usuario en una ventana de redacción de la IU de Gmail. Puedes crear el borrador como un mensaje nuevo o como una respuesta al mensaje abierto en Gmail. Cuando el controlador llama a la función de devolución de llamada de compilación de borrador, pasa un objeto de evento a la función de devolución de llamada. Consulta Cómo redactar mensajes para obtener más detalles.
setOnClickOpenLinkAction El usuario hace clic en el widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Establece un Action para abrir una URL cuando el usuario haga clic en el widget. Usa este controlador cuando debas construir la URL o se deban realizar otras acciones antes de que se abra el vínculo. De lo contrario, suele ser más sencillo usar setOpenLink. Solo puedes abrir la URL en una ventana nueva. Cuando se cierra, puedes hacer que la IU vuelva a cargar el complemento.
setOpenLink El usuario hace clic en el widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Abre directamente una URL cuando el usuario hace clic en el widget. Usa este controlador cuando conozcas la URL y solo necesites abrirla. De lo contrario, usa setOnClickOpenLinkAction. Puedes abrir la URL en una ventana nueva o en una superposición. Cuando se cierra, puedes hacer que la IU vuelva a cargar el complemento.
setSuggestionsAction El usuario ingresa texto en una entrada. TextInput Establece un Action que ejecuta una función de Apps Script cuando el usuario ingresa texto en un widget de entrada de texto. El controlador pasa automáticamente un objeto de evento a la función que llama. Consulta Sugerencias de autocompletado para entradas de texto para obtener más información.

Funciones de devolución de llamada

Las funciones de devolución de llamada se ejecutan cuando se activa un Action. Dado que las funciones de devolución de llamada son funciones de Apps Script, puedes hacer que realicen casi cualquier tarea que pueda realizar cualquier otra función de secuencia de comandos.

A veces, una función de devolución de llamada devuelve un objeto de respuesta específico. Estos tipos de respuestas indican operaciones adicionales que deben ocurrir después de que finalice la ejecución de la devolución de llamada, como mostrar una tarjeta nueva o presentar sugerencias de autocompletar. Cuando tu función de devolución de llamada debe devolver un objeto de respuesta específico, usas una clase de compilador en el servicio de tarjetas para compilar ese objeto.

En la siguiente tabla, se muestra cuándo tus funciones de devolución de llamada deben devolver un objeto de respuesta específico para acciones específicas. Todas estas acciones son independientes de la aplicación host específica que extiende el complemento:

Acción intentada La función de devolución de llamada debe devolver
Navegar ActionResponse
Muestra un Notification ActionResponse
Cómo abrir un vínculo con setOnClickOpenLinkAction ActionResponse
Mostrar sugerencias de autocompletar SuggestionResponse
Usa una acción universal UniversalActionResponse
Otras acciones Nothing

Acciones para las aplicaciones host de Google Workspace

Además de estas acciones, cada aplicación host tiene su propio conjunto de acciones que solo se pueden realizar en ese host. Para obtener más detalles, consulta las siguientes guías:

Cuando uses las clases de compilador de respuestas, llama al método build para producir los objetos de respuesta. De lo contrario, se producirá un error.

Las acciones universales se definen en el manifiesto del proyecto y no necesitan objetos Action, pero sus funciones de devolución de llamada deben devolver un UniversalActionResponse.

Objetos de eventos de acción

Cuando tu complemento activa un Action, la IU construye automáticamente un objeto de evento JSON y lo pasa como argumento a la función de devolución de llamada Action. Este objeto de evento contiene información sobre el contexto actual del cliente del usuario, como los valores actuales de todos los widgets interactivos de la tarjeta que se muestra.

Los objetos de eventos de acción tienen una estructura JSON específica que organiza la información que contienen. Se usa la misma estructura cuando se activa un activador de página principal para crear una página principal o cuando se activa un activador contextual para actualizar la pantalla del complemento.

Consulta Objetos de evento para obtener una explicación completa de la estructura de los objetos de evento.

Los complementos de Gmail usaban una versión simplificada de esta estructura de objetos de eventos, que ahora dejó de estar disponible. Para garantizar la compatibilidad con versiones anteriores, todos los campos del objeto de evento original de los complementos de Gmail aún se incluyen en la nueva estructura del objeto de evento (consulta la estructura del objeto de evento). Sin embargo, la misma información se reproduce en las subestructuras de los objetos commonEventObject y Gmail event. Si actualizas un complemento de Gmail a un complemento de Google Workspace, ajusta tu código para usar los campos actualizados del objeto de evento. Con el tiempo, se quitarán los campos del objeto de evento original de Gmail.