Compila interfaces de Google Drive

Los complementos de Google Workspace pueden proporcionar interfaces personalizadas cuando un usuario abre Drive. Esto te permite proporcionar al usuario información adicional relevante, automatizar tareas y conectar sistemas de terceros a Drive.

Accede a la IU del complemento de Google Workspace

Puedes abrir el complemento en Drive si su ícono aparece en la columna de íconos del lado derecho de la interfaz de usuario de Drive. Un complemento 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 Drive, el complemento ejecuta la función drive.homepageTrigger correspondiente (si está presente). Esta función compila y devuelve una tarjeta de página principal para que se muestre en Drive. Si no se define ninguna función de drive.homepageTrigger, se mostrará una tarjeta genérica de la página principal.
  • Si el usuario selecciona uno o más elementos en Drive y, luego, hace clic en el ícono del complemento, o bien selecciona elementos mientras el complemento está abierto, el complemento ejecuta la función contextual drive.onItemsSelectedTrigger correspondiente (si está presente). Esta función compila la interfaz contextual "elementos seleccionados" del complemento de Drive y la devuelve a Drive para que se muestre.

Cómo compilar la interfaz del complemento de Drive

Sigue estos pasos generales para compilar interfaces que extiendan Drive:

  1. Decide si quieres que tu complemento tenga una página principal específica de Drive. También decide si deseas proporcionar una interfaz contextual para cuando el usuario seleccione elementos de Drive.
  2. Agrega los campos addOns.common y addOns.drive correspondientes al manifiesto del proyecto de la secuencia de comandos del complemento, incluidos los alcances de Drive necesarios.
  3. Si proporcionas una página principal específica de Drive, implementa la función drive.homepageTrigger para compilar esta interfaz. También puedes usar la interfaz de common.homepageTrigger para varios hosts de Google Workspace.
  4. Si proporcionas una interfaz de selección de elementos contextuales de Drive, debes implementar una función de activación contextual drive.onItemsSelectedTrigger para compilar esta interfaz. Consulta Interfaz contextual de Drive para los elementos seleccionados para obtener más detalles.
  5. Implementa las funciones de devolución de llamada asociadas necesarias para responder a las interacciones del usuario con la IU, como los clics en botones.

Páginas principales de Drive

Drive admite la visualización de páginas principales de complementos. Para mostrar la página principal común de tu complemento en 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, proporciona 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. Implementa esta función para compilar y devolver un solo objeto Card o un array de objetos Card que componen la página principal. A la función de activación de la página principal se le pasa un objeto de evento como parámetro que contiene información general, como la plataforma del cliente. Usa los datos del objeto de evento para compilar la página principal.

Interfaz contextual de Drive para los elementos seleccionados

Drive se basa en un activador contextual para determinar qué interfaz (si corresponde) mostrar cuando el usuario selecciona uno o más elementos de 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.

Para crear una interfaz de selección de elementos contextuales para Drive, debes hacer lo siguiente:

  1. Asegúrate de que el manifiesto del complemento incluya el permiso https://www.googleapis.com/auth/drive.addons.metadata.readonly.

  2. Asegúrate de que el manifiesto incluya una sección drive.onItemsSelectedTrigger.

  3. Implementa la función que se nombra en el campo drive.onItemsSelectedTrigger. Esta función acepta un objeto de evento como argumento y debe devolver un solo objeto Card o un array de objetos Card.

  4. Al igual que con cualquier tarjeta, implementa las funciones de devolución de llamada que se usan para proporcionar interactividad del widget a la interfaz. Por ejemplo, si incluyes un botón en la interfaz, este debe tener un objeto Action adjunto y una función de devolución de llamada implementada que se ejecute cuando se haga clic en el botón.

Objetos de eventos

Se crea un objeto de evento y se pasa a la función de activación drive.homepageTrigger o drive.onItemsSelectedTrigger cuando se llaman a esas funciones. La función de activación usa la información de este objeto de evento para determinar cómo compilar tarjetas de complementos o controlar el comportamiento del complemento de otra manera.

La estructura completa de los objetos de evento se describe en Objetos de evento. Cuando Drive es la app host del 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 de Drive contextuales para los activadores de selección de elementos incluyen información sobre los elementos que el usuario seleccionó cuando se activó el activador. Cuando un usuario selecciona más de un elemento en Drive, uno de ellos se considera de interés principal, y se lo conoce como el elemento del cursor activo.

Si el comportamiento del complemento debe aplicarse a varios elementos seleccionados, usa la información proporcionada en el array drive.selectedItems del objeto de evento para identificarlos todos.

Cuando el comportamiento de un complemento solo se debe aplicar a un elemento seleccionado, usa la información proporcionada en el campo drive.activeCursorItem del objeto de evento para identificar el elemento de la selección completa. No intentes inferir qué elemento usar del array drive.selectedItems.

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"
      },
      ...
    ]
  },
  ...
}