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 con los 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 la creas. 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 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
con este proceso general:
- Crea el objeto
Action
y especifica la función de devolución de llamada que debe ejecutar junto con los parámetros que requiera. - Llama a la función del controlador de widgets adecuada en el widget con el objeto
Action
. - Implementa la función de devolución de llamada para aplicar el comportamiento requerido.
Funciones del controlador de widgets
Para vincular un widget a un Action
específico o a otro comportamiento, debes usar 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 qué pasos realiza la IU,
si los hay, 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 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, 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 adicionales 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, 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 una respuesta al mensaje abierto en Gmail. Cuando el controlador llama a la función de devolución de llamada de compilación de borradores, 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 hace clic en el widget. Usa este controlador cuando debes construir la URL o cuando deben realizarse 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 a la 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 hagan casi cualquier cosa que pueda hacer cualquier otra función de secuencia de comandos.
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 finaliza la ejecución de la devolución de llamada, 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, debes usar una clase de compilador en el servicio de tarjetas para crear 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 de host específica que extiende el complemento:
Intento de acción | La función de devolución de llamada debe mostrar |
---|---|
Navega entre las tarjetas | ActionResponse |
Muestra un Notification |
ActionResponse |
Cómo abrir un vínculo con setOnClickOpenLinkAction() |
ActionResponse |
Cómo mostrar sugerencias de autocompletar | SuggestionResponse |
Usa una acción universal. | UniversalActionResponse |
Otras acciones | Nothing |
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 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 del cliente actual 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 visualización del complemento.
Consulta Objetos de evento para obtener una explicación completa de la estructura de los objetos de evento.