Las acciones de complementos proporcionan un comportamiento interactivo para widgets. Cuando creas una acción, tú defines qué sucede cuando el usuario selecciona o actualiza un widget.
En la mayoría de los casos, puedes definir acciones de complementos usando
Action
Objetos proporcionados por 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 dar los pasos deseados cuando el usuario interactúa con el widget. También debes
Vincula Action al widget
usando una función controladora de widgets adecuada que
define el tipo de interacción que activa
Action de devolución de llamada.
Configura un widget con una Action
con este proceso general:
- Crea el objeto
Action. especificando la función de devolución de llamada que debería ejecutar junto con cualquier parámetro requerido. - Llama a la función del controlador del widget que corresponda.
en el widget con
Action. - Implementa la función de devolución de llamada para ejecutar el comportamiento requerido.
Funciones del controlador de widgets
Para vincular un widget a una Action específica
u otro comportamiento, usas un widget
la función de controlador. La función de controlador determina el tipo de interacción
(por ejemplo, hacer clic en el widget o editar un campo de texto) activa el
de la acción. La función del controlador también define los pasos que sigue la IU
si los hay, después de que se complete la acción.
En la siguiente tabla, se enumeran los diferentes tipos de controladores para widgets y cuáles widgets con los que se usan:
| Función del controlador | Activa una acción | Widgets aplicables | Descripción |
|---|---|---|---|
setOnChangeAction() |
Cambia el valor del widget |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Establece un Action.
que ejecuta una función de Apps Script cuando el widget pierde el foco, como
como cuando el usuario ingresa texto en una entrada y presiona Intro. El
controlador automáticamente pasa una
event object a la función a la que llama.
Puedes insertar información adicional del parámetro en este objeto de evento
si lo deseas. |
setOnClickAction() |
El usuario hace clic en el widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Establece un Action.
que ejecuta una función de Apps Script cuando el usuario hace clic en el widget. El
controlador automáticamente pasa una
event object a la función a la que llama.
Puedes insertar información del parámetro opcional en este objeto de evento. |
setComposeAction() |
El usuario hace clic en el widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Específico de Gmail. Establece un
Action
que crea un borrador de correo electrónico y, luego, presenta ese borrador al usuario en un
Ventana de redacción de la IU de Gmail. Puedes crear el borrador como un mensaje nuevo o como
responder al mensaje abierto en Gmail. Cuando el controlador llama a
de devolución de llamada de compilación de borrador, pasa un
event object a la función de devolución de llamada.
Consulta
Cómo redactar borradores de mensajes
para obtener más información. |
setOnClickOpenLinkAction() |
El usuario hace clic en el widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Establece un Action.
para abrir una URL cuando el usuario haga clic en el widget. Usa este controlador cuando
Debe crear la URL o realizar otras acciones antes del vínculo.
abre; De lo contrario, suele ser más fácil usar setOpenLink().
Solo puedes abrir la URL en una ventana nueva. Cuando se cierra, puedes provocar que
IU para volver a cargar el complemento. |
setOpenLink() |
El usuario hace clic en el widget |
CardActionImageImageButtonDecoratedTextTextButton
|
Abre directamente una URL cuando el usuario hace clic en el widget. Usar esta
cuando conoces la URL y solo necesitas abrirla; De lo contrario, utiliza
setOnClickOpenLinkAction()
Puedes abrir la URL en una ventana nueva o en una superposición. Cuando está cerrado, usted
puede 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 una
de entrada de texto. El controlador pasa automáticamente un
event object a la función a la que llama.
Consulta
Sugerencias de autocompletar
para entradas de texto y obtén más detalles. |
Funciones de devolución de llamada
Las funciones de devolución de llamada se ejecutan cuando un elemento Action
activadores. Dado que las funciones de devolución de llamada son funciones de Apps Script, puedes elegirlas
hacer casi cualquier cosa que cualquier otra función de secuencia de comandos puede hacer.
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 cuando termine 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 valor de respuesta, debes usar una clase de compilador en el servicio de Card. para construir ese objeto.
En la siguiente tabla, se muestra cuándo las funciones de devolución de llamada deben mostrar un un objeto de respuesta específico para acciones específicas. Todas estas acciones independiente de la aplicación host específica que extiende el complemento:
| Acción realizada | La función de devolución de llamada debería mostrar |
|---|---|
| Cómo navegar entre tarjetas | ActionResponse |
Muestra un elemento Notification. |
ActionResponse |
Abre un vínculo con setOnClickOpenLinkAction(). |
ActionResponse |
| Cómo mostrar sugerencias de autocompletar | SuggestionResponse |
| Usar 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 pueden realizarse en ese host. Para obtener más información, consulta los siguientes vínculos: guías:
Objetos de eventos de acción
Cuando el complemento activa una Action,
la IU construye automáticamente un objeto de evento JSON y lo pasa como un
argumento para la devolución de llamada Action
. Este objeto de evento contiene información sobre el estado
el contexto del cliente, como los valores actuales de todas las etiquetas
widgets en la tarjeta que se muestra.
Los objetos de eventos de acción tienen una estructura JSON específica que organiza las la información que contienen. Se usa la misma estructura cuando activador de la página principal para crear una página de inicio. activador contextual se activa para actualizar la pantalla del complemento.
Consulta Objetos de evento para ver una de la estructura de objetos del evento.