Acciones de complementos

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:

  1. Crea el objeto Action. especificando la función de devolución de llamada que debería ejecutar junto con cualquier parámetro requerido.
  2. Llama a la función del controlador del widget que corresponda. en el widget con Action .
  3. 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 DatePicker
DateTimePicker
SelectionInput
Switch
TextInput 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 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 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 CardAction
Image
ImageButton
DecoratedText
TextButton
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 CardAction
Image
ImageButton
DecoratedText
TextButton
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 CardAction
Image
ImageButton
DecoratedText
TextButton
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.