Acciones de complementos

Las acciones de complemento proporcionan un 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 complemento con objetos Action proporcionados por el servicio de tarjeta de Apps Script. Cada Action se asocia a una función de devolución de llamada cuando la creas. Implementas la función de devolución de llamada para seguir los pasos deseados 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 Action.

Configura un widget con un Action mediante este proceso general:

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 widget correspondiente en el widget con el objeto Action.
3. Implementa la función de devolución de llamada para implementar el comportamiento requerido.

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

Funciones del controlador de widgets

Para vincular un widget a un Action específico o algún otro comportamiento, usa una función de controlador de widget. 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 del controlador también define los pasos que realiza la IU, si corresponde, después de que se completa la acción.

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

Función del controlador	Activa la acción	Widgets aplicables	Descripción
setOnChangeAction()	El valor del widget cambia	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	Configura un Action que ejecuta una función de Apps Script cuando el widget pierde el foco. Por ejemplo, cuando el usuario ingresa texto en una entrada y presiona Intro. El controlador pasa automáticamente un objeto de evento a la función a la que llama. Si lo deseas, puedes insertar información de parámetros adicional en este objeto de evento.
setOnClickAction()	El usuario hace clic en el widget.	CardAction Image ImageButton DecoratedText TextButton	Configura 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 a la que llama. Puedes insertar información de parámetros opcional en este objeto de evento.
setComposeAction()	El usuario hace clic en el widget.	CardAction Image ImageButton DecoratedText TextButton	Específico de Gmail. Establece un Action que crea un borrador de correo electrónico y, luego, lo presenta al usuario en una ventana de redacción de 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 en borrador, pasa un objeto de evento a la función de devolución de llamada. Para obtener más detalles, consulta Cómo redactar mensajes en borrador.
setOnClickOpenLinkAction()	El usuario hace clic en el widget.	CardAction Image ImageButton DecoratedText TextButton	Configura un Action para abrir una URL cuando el usuario hace clic en el widget. Usa este controlador cuando sea necesario construir la URL o realizar otras acciones antes de que se abra el vínculo; de lo contrario, suele ser más fácil 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	Configura 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 a la que llama. Si deseas obtener más información, consulta Sugerencias de autocompletado para entradas de texto.

Funciones de devolución de llamada

Las funciones de devolución de llamada se ejecutan cuando se activa un Action. Debido a que la función de devolución de llamada son funciones de Apps Script, puedes hacer que hagan casi cualquier cosa que cualquier otra función de secuencia de comandos puede hacer.

Advertencia: El servicio de tarjetas de Apps Script 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 que eso, es posible que la IU del complemento no actualice correctamente la visualización de la tarjeta en respuesta al Action.

A veces, una función de devolución de llamada muestra un objeto de respuesta específico. Estos tipos de respuestas indican operaciones adicionales que deben ocurrir después de que la devolución de llamada termina de ejecutarse, como mostrar una tarjeta nueva o presentar sugerencias de autocompletado. Cuando tu función de devolución de llamada debe mostrar un objeto de respuesta específico, usas una clase de compilador en el servicio de Card para construir ese objeto.

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

Intento de acción	Se debería mostrar la función de devolución de llamada
Navegar entre tarjetas	ActionResponse
Muestra un elemento Notification.	ActionResponse
Abre un vínculo usando setOnClickOpenLinkAction()	ActionResponse
Muestra sugerencias de autocompletado	SuggestionResponse
Utilizar una acción universal	UniversalActionResponse
Otras acciones	Nada

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:

• Acciones de Calendario
• Generar acciones
• Acciones de Gmail
• Acciones del editor

Nota: Cuando uses las clases de compilador de respuestas, asegúrate de llamar a build() para producir los objetos de respuesta. Si no lo haces, se generará un error.

Nota: Las acciones universales se definen en el manifiesto del proyecto y no necesitan objetos Action, pero sus funciones de devolución de llamada deben mostrar 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 de complemento.

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

Nota: Los complementos de Gmail usaban una versión simplificada de esta estructura de objetos de evento, que ahora dejó de estar disponible. Para ofrecer retrocompatibilidad, todos los campos originales de los objetos de evento del complemento de Gmail aún se encuentran dentro de la nueva estructura de objetos de eventos (consulta la estructura de objetos de eventos). Sin embargo, la misma información se reproduce en las subestructuras de objetos de eventos comunes y de eventos de Gmail. Si actualizas un complemento de Gmail a un complemento de Google Workspace, debes ajustar tu código para usar los campos de objeto de evento actualizados; con el tiempo, los campos de objetos de evento de Gmail originales se quitarán.