Compila interfaces de Google Editor

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 el EDITOR_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 llamado EDITOR_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:

  1. Agrega los campos addOns.common, addOns.docs, addOns.sheets y addOns.slides adecuados al manifiesto del proyecto de secuencia de comandos del complemento.
  2. Agrega los permisos de Editor necesarios al manifiesto del proyecto de secuencia de comandos.
  3. 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 interfaz common.homepageTrigger a fin de compilar una página de inicio común para tus apps host.
  4. Si usas las APIs de REST, implementa el flujo de autorización del alcance drive.file y la función del activador EDITOR_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.
  5. 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ón linkPreviewTriggers. Para obtener más información, consulta Interfaces de la vista previa del vínculo.
  6. 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.

  1. 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".
  2. 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 objeto Card o un array de objetos Card.
  3. 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"
     }
   }

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