Los complementos de Google Workspace pueden proporcionar interfaces personalizadas cuando el usuario usa Google Drive. Esto te permite proporcionar al usuario información relevante adicional, automatizar tareas y conectar sistemas de terceros a Google Drive.
Cómo acceder a la IU del complemento
Puedes abrir un complemento de Google Workspace en Google Drive si su ícono aparece en la columna de íconos del lado derecho de la interfaz de usuario de Drive. Un complemento de Google Workspace puede definir una interfaz de página principal, una interfaz de selección de elementos o ambas:
- Si un usuario hace clic en el ícono del complemento mientras está en Google Drive, el complemento ejecuta la función
drive.homepageTrigger
correspondiente (si está presente). Esta función compila y muestra una tarjeta de página principal en Google Drive para que se muestre. Si no se define ninguna funcióndrive.homepageTrigger
, se muestra una tarjeta genérica de la página principal en su lugar. - Si el usuario selecciona uno o más elementos en Google Drive y, luego, hace clic en el ícono del complemento o selecciona elementos mientras el complemento está abierto, este ejecuta la función contextual
drive.onItemsSelectedTrigger
correspondiente (si está presente). Esta función compila la interfaz de "elementos seleccionados" de Google Drive del complemento y la muestra en Google Drive para su visualización.
Cómo compilar la interfaz de complemento de Drive
Puedes compilar interfaces que extiendan Google Drive si sigues estos pasos generales:
- Decide si quieres que tu complemento tenga una página principal específica de Drive. También decide si quieres proporcionar una interfaz contextual para cuando el usuario seleccione elementos de Drive.
- Agrega los campos
addOns.common
yaddOns.drive
correspondientes al manifiesto del proyecto de secuencia de comandos de complementos, incluidos los permisos de Drive necesarios. - Si proporcionas una página principal específica de Drive, implementa la función
drive.homepageTrigger
para compilar esta interfaz. También puedes optar por usar la interfazcommon.homepageTrigger
para varios hosts de Google Workspace. - Si proporcionas una interfaz de selección de elementos contextuales de Drive, debes implementar una función de activador contextual
drive.onItemsSelectedTrigger
para compilar esta interfaz. Consulta Interfaz contextual de Drive para elementos seleccionados) a fin de obtener más detalles. - 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ágina principal de Drive
Google Drive admite mostrar las páginas principales del complemento de Google Workspace.
Para mostrar la página principal común de tu complemento en Google Drive, asegúrate de que haya un campo addOns.drive
en el manifiesto del complemento.
Como alternativa, agrega un drive.homepageTrigger
al manifiesto del complemento para proporcionar una página principal específica de Drive.
En cualquier caso, debes proporcionar el nombre de una función de activación de la página principal en el proyecto de secuencia de comandos de tu complemento. Esta función se llama automáticamente para compilar la página principal de Drive cuando es necesario. Debes implementar esta función para compilar y mostrar un solo objeto Card
o un array de objetos Card
que conforman la página principal. La función de activación de la página principal recibe un objeto de evento como un parámetro que contiene información general, como la plataforma del cliente. Puedes usar los datos del objeto de evento para adaptar la construcción de la página principal.
Interfaz contextual de Drive para los elementos seleccionados
Google Drive se basa en un activador contextual para determinar qué interfaz (si corresponde) mostrar cuando el usuario selecciona uno o más elementos de Google Drive. Cuando se activa el activador, se ejecuta la función de activación contextual especificada por el campo drive.onItemsSelectedTrigger.runFunction
en el manifiesto del complemento.
Si deseas crear una interfaz de selección de elementos contextuales para Drive, debes hacer lo siguiente:
Asegúrate de que el manifiesto del complemento incluya el permiso de
https://www.googleapis.com/auth/drive.addons.metadata.readonly
.Asegúrate de que el manifiesto incluya una sección
drive.onItemsSelectedTrigger
.Implementa la función nombrada en el campo
drive.onItemsSelectedTrigger
. 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 cualquier función de devolución de llamada que se use 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.
Objetos de evento
Cuando se llama a esas funciones, se crea un objeto de evento y se pasa a la función de activador drive.homepageTrigger
o drive.onItemsSelectedTrigger
. La función del activador puede usar
la información de este objeto de 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 Drive es la app host que actúa en el complemento, los objetos de eventos contextuales incluyen el campo Objeto de evento de Drive, que contiene información específica del cliente de Drive.
Los objetos de eventos contextuales de Drive para los activadores de selección de elementos incluyen información sobre los elementos que el usuario seleccionó cuando se activa el activador. Cuando un usuario selecciona más de un elemento en Drive, uno de ellos se considera de interés principal. Este elemento se conoce como el elemento de cursor activo.
En el siguiente ejemplo, se muestra un objeto de evento de Drive que se pasa a una función drive.onItemsSelectedTrigger
:
{
"commonEventObject": { ... },
"drive": {
"activeCursorItem":{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl": "https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
"selectedItems": [
{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl":"https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
...
]
},
...
}