Acciones de complementos

Las acciones de complementos 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 complementos mediante objetos Action que proporciona el servicio de tarjetas de Apps Script. Cada Action se asocia con una función de devolución de llamada cuando se crea. Implementas la función de devolución de llamada para realizar 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 widget 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 ejecutarse junto con los parámetros que requiera.
  2. Llama a la función del controlador de widgets adecuada en el widget con el objeto Action.
  3. Implementa la función de devolución de llamada para implementar el comportamiento requerido.

Funciones del controlador de widgets

Para vincular un widget a un Action específico 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 del controlador también define los pasos que realiza la IU, si los hubiera, después de que se completa la acción.

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

Función de controlador Activa una 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 foco, 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 a la que llama. Si lo deseas, puedes insertar información adicional de parámetros en este objeto de evento.
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 a la 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 Action que compila un borrador de correo electrónico y, luego, 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 en borrador para obtener más detalles.
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 debas construir la URL, o bien 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. Una vez cerrado, 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. Una vez cerrado, 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 a la que llama. Para obtener más detalles, consulta Sugerencias de autocompletar para entradas de texto.

Funciones de devolución de llamada

Las funciones de devolución de llamada se ejecutan cuando se activa una Action. Dado que las funciones de devolución de llamada son funciones de Apps Script, puedes hacer que hagan casi todo lo que pueden hacer las otras funciones de secuencias de comandos.

Una función de devolución de llamada a veces muestra un objeto de respuesta específico. Estos tipos de respuestas indican operaciones adicionales que deben realizarse después de que termina de ejecutarse la devolución de llamada, como mostrar una tarjeta nueva o presentar sugerencias de autocompletar. Cuando la función de devolución de llamada debe mostrar un objeto de respuesta específico, debes usar una clase de compilador en el servicio de tarjetas para construir ese objeto.

En la siguiente tabla, se indica cuándo las 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 host específica que extiende el complemento:

Acción que se intentó La función de devolución de llamada debería mostrar
Cómo navegar entre tarjetas ActionResponse
Muestra un Notification. ActionResponse
Abrir un vínculo con setOnClickOpenLinkAction() ActionResponse
Muestra sugerencias de autocompletar SuggestionResponse
Usar 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:

Objetos de eventos de acción

Cuando el complemento activa un Action, la IU crea 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. La misma estructura se usa cuando un activador de página principal se activa para crear una página principal o cuando un activador contextual se activa para actualizar la pantalla del complemento.

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