Con los complementos de Google Workspace, puedes proporcionar interfaces personalizadas dentro de los editores, incluidos Documentos, Hojas de cálculo y Presentaciones de Google. Esto te permite proporcionar al usuario información relevante, automatizar tareas y conectar sistemas de terceros con los editores.
Cómo acceder a la IU del complemento
Puedes abrir un complemento de Google Workspace en los editores si su ícono aparece en el panel lateral de acceso rápido de Google Workspace, en el lado derecho de las interfaces de usuario de Documentos, Hojas de cálculo y Presentaciones.
Un complemento de Google Workspace puede presentar las siguientes interfaces:
Interfaces de la página principal: Si el manifiesto del complemento incluye el activador
EDITOR_NAME.homepageTrigger
para el Editor en el que el usuario lo abre, este lo compila y muestra una tarjeta de la página principal específicamente para ese Editor. Si el manifiesto del complemento no incluye elEDITOR_NAME.homepageTrigger
para el editor en el que el usuario lo abre, se mostrará una tarjeta genérica de la página principal.Interfaces de la API de REST: Si el complemento usa las APIs de REST, puedes incluir activadores que soliciten acceso por archivo a un documento con el alcance
drive.file
. Una vez otorgado, otro activador llamadoEDITOR_NAME.onFileScopeGrantedTrigger
se ejecuta y muestra una interfaz específica para el archivo.Interfaces de vista previa de vínculos: Si tu complemento se integra en un servicio de terceros, puedes compilar tarjetas que obtengan una vista previa del contenido de las URLs del servicio.
Cómo compilar interfaces para complementos del editor
Sigue estos pasos para compilar las interfaces del complemento de editor para los editores:
- Agrega los campos
addOns.common
,addOns.docs
,addOns.sheets
yaddOns.slides
adecuados al manifiesto del proyecto de secuencia de comandos del complemento. - Agrega los permisos de Editor necesarios al manifiesto del proyecto de secuencia de comandos.
- Si proporcionas una página principal específica de Editor, implementa la función
EDITOR_NAME.homepageTrigger
para compilar la interfaz. De lo contrario, usa la interfazcommon.homepageTrigger
a fin de compilar una página de inicio común para tus apps host. - Si usas las APIs de REST, implementa el flujo de autorización del alcance
drive.file
y la función del activadorEDITOR_NAME.onFileScopeGrantedTrigger
para mostrar una interfaz específica para el archivo abierto. Para obtener más información, consulta Interfaces de la API de REST. - Si configuras vistas previas de vínculos desde un servicio de terceros, implementa el flujo de autorización de alcance
https://www.googleapis.com/auth/workspace.linkpreview
y la funciónlinkPreviewTriggers
. Para obtener más información, consulta Interfaces de la vista previa del vínculo. - Implementa las funciones de devolución de llamada asociadas necesarias para responder a las interacciones del usuario en la IU, como los clics en un botón.
Páginas principales del editor
Debes proporcionar una función de activación de la página principal en el proyecto de secuencia de comandos de tu complemento que compile y muestre un solo Card
o un array de objetos Card
que conforman la página principal del complemento.
La función de activación de la página principal recibe un objeto de evento como un parámetro que contiene información como la plataforma del cliente. Puedes usar los datos del objeto de evento para adaptar la construcción de la página de inicio.
Puedes presentar una página principal común o una página principal que sea específica del Editor en el que el usuario abre tu complemento.
Mostrar la página principal común
Para mostrar la página principal común de tu complemento en los Editores, incluye los campos correspondientes del editor, como addOns.docs
, addOns.sheets
o addOns.slides
, en el manifiesto del complemento.
En el siguiente ejemplo, se muestra la parte addons
de un manifiesto de complemento de Google Workspace. El complemento extiende Documentos, Hojas de cálculo y Presentaciones, y muestra la página principal común en cada app host.
"addOns": { "common": { "name": "Translate", "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png", "layoutProperties": { "primaryColor": "#2772ed" }, "homepageTrigger": { "runFunction": "onHomepage" } }, "docs": {}, "sheets": {}, "slides": {} } }
Mostrar una página principal específica de Editor
Para presentar una página principal específica a un editor, agrega EDITOR_NAME.homepageTrigger
al manifiesto del complemento.
En el siguiente ejemplo, se muestra la parte addons
de un manifiesto de complemento de Google Workspace.
El complemento está habilitado para Documentos, Hojas de cálculo y Presentaciones. Muestra la página principal común en Documentos y Presentaciones, y una página principal única en Hojas de cálculo. La función de devolución de llamada onSheetsHomepage
compila la tarjeta de la página principal específica de Hojas de cálculo.
"addOns": { "common": { "name": "Translate", "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png", "layoutProperties": { "primaryColor": "#2772ed" }, "homepageTrigger": { "runFunction": "onHomepage" } }, "docs": {}, "slides": {}, "sheets": { "homepageTrigger": { "runFunction": "onSheetsHomepage" }, } }
Interfaces de la API de REST
Si tu complemento usa APIs de REST, como la API de Hojas de cálculo de Google,
puedes usar la función onFileScopeGrantedTrigger
para mostrar una nueva interfaz
específica para el archivo que se abre en la app host de Editor.
Debes incluir el flujo de autorización de alcance drive.file
para usar la función onFileScopeGrantedTrigger
. Si quieres aprender a solicitar el alcance de drive.file
, consulta Cómo solicitar acceso al archivo para el documento actual.
Cuando un usuario otorga el alcance drive.file
, se activa EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
. Cuando el activador se activa, ejecuta la función de activador contextual que especifica el campo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
en el manifiesto del complemento.
A fin de crear una interfaz de la API de REST para uno de los editores, sigue los pasos que se indican a continuación.
Reemplaza EDITOR_NAME
por la app host de Editor que elijas usar, por ejemplo, sheets.onFileScopeGrantedTrigger
.
- Incluye
EDITOR_NAME.onFileScopeGrantedTrigger
en la sección del editor correspondiente de tu manifiesto. Por ejemplo, si quieres crear esta interfaz en Hojas de cálculo de Google, agrega el activador a la sección"sheets"
. - Implementa la función nombrada en la sección
EDITOR_NAME.onFileScopeGrantedTrigger
. Esta función acepta un objeto de evento como argumento y debe mostrar un solo objetoCard
o un array de objetosCard
. - Al igual que con cualquier tarjeta, debes implementar las funciones de devolución de llamada que se usan para proporcionar interactividad del widget para la interfaz. Por ejemplo, si incluyes un botón en la interfaz, este debería tener una Action adjunta y una función de devolución de llamada implementada que se ejecute cuando se hace clic en el botón.
En el siguiente ejemplo, se muestra la parte addons
de un manifiesto de complemento de Google Workspace.
El complemento usa las API de REST, por lo que se incluye onFileScopeGrantedTrigger
para Hojas de cálculo de Google. Cuando un usuario otorga el alcance drive.file
, la función de devolución de llamada onFileScopeGrantedSheets
compila una interfaz específica del archivo.
"addOns": { "common": { "name": "Productivity add-on", "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png", "layoutProperties": { "primaryColor": "#669df6", "secondaryColor": "#ee675c" } }, "sheets": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedSheets" } }
Cómo vincular interfaces de vista previa para servicios de terceros
Si quieres activar las vistas previas de vínculos para un servicio de terceros, debes configurarlas en el manifiesto de tu complemento y crear una función que muestre una tarjeta de vista previa. Para los servicios que requieren la autorización del usuario, tu función también debe invocar el flujo de autorización.
Si quieres conocer los pasos para activar las vistas previas de vínculos, consulta Cómo obtener una vista previa de vínculos con chips inteligentes.
Objetos de evento
Se crea un objeto de evento y se pasa para activar funciones, como EDITOR_NAME.homepageTrigger
o EDITOR_NAME.onFileScopeGrantedTrigger
. La función del activador usa la información del objeto del evento para determinar cómo crear tarjetas de complementos o controlar el comportamiento del complemento.
La estructura completa de los objetos de evento se describe en Objetos de evento.
Cuando un editor es la app de host activa del complemento, los objetos de evento incluyen campos de objetos de evento de Documentos, Hojas de cálculo o Presentaciones que contienen información del cliente.
Si el complemento no tiene autorización de alcance de drive.file
para el usuario o documento actual, el objeto de evento solo contiene los campos docs.addonHasFileScopePermission
, sheets.addonHasFileScopePermission
o slides.addonHasFileScopePermission
. Si el complemento tiene autorización, el objeto de evento contiene todos los campos del objeto de evento de Editor.
En el siguiente ejemplo, se muestra un objeto de evento Editor que se pasa a una función sheets.onFileScopeGrantedTrigger
. Aquí, el complemento tiene la autorización de alcance drive.file
para el documento actual:
` { "commonEventObject": { ... }, "sheets": { "addonHasFileScopePermission": true, "id":"A_24Q3CDA23112312ED52", "title":"How to get started with Sheets" }, ... }