Cómo compilar interfaces de Editor de Google

Con los complementos de Google Workspace, puedes proporcionar interfaces personalizadas en los editores, incluidos Documentos, Hojas de cálculo y Presentaciones de Google. Esto te permite proporcionarle al usuario información relevante, automatizar tareas y conectar sistemas de terceros a 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, a la derecha de las interfaces de usuario de Documentos, Hojas de cálculo y Presentaciones.

Un complemento de Google Workspace puede presentar las siguientes interfaces:

  • Interfaz de la página principal: Si el manifiesto del complemento incluye el activador EDITOR_NAME.homepageTrigger para el editor en el que el usuario abre el complemento, este se 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 muestra una tarjeta de página principal genérica.

  • Interfaces de la API de REST: Si el complemento usa APIs de REST, puedes incluir activadores que soliciten acceso por archivo a un documento con el permiso drive.file. Una vez otorgado, se ejecuta otro activador llamado EDITOR_NAME.onFileScopeGrantedTrigger y se muestra una interfaz específica del archivo.

  • Interfaz de vista previa de vínculos: Si tu complemento se integra con un servicio de terceros, puedes crear tarjetas que muestren una vista previa del contenido de las URLs de tu servicio.

Cómo compilar interfaces para complementos de Editor

Sigue estos pasos para compilar interfaces de complementos de editores para los editores:

  1. Agrega los campos addOns.common, addOns.docs, addOns.sheets y addOns.slides apropiados al manifiesto del proyecto de secuencia de comandos del complemento.
  2. Agrega los alcances del editor necesarios al manifiesto de tu proyecto de secuencia de comandos.
  3. Si proporcionas una página principal específica del editor, implementa la función EDITOR_NAME.homepageTrigger para compilar la interfaz. De lo contrario, usa la interfaz common.homepageTrigger para crear una página principal común para tus apps de host.
  4. Si usas APIs de REST, implementa el flujo de autorización de alcance drive.file y la función de activación EDITOR_NAME.onFileScopeGrantedTrigger para mostrar una interfaz específica del 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 vista previa de vínculos.
  6. Implementa las funciones de devolución de llamada asociadas necesarias para responder a las interacciones del usuario con la IU, como los clics en los botones.

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 del complemento que compile y muestre un solo Card o un array de objetos Card que conforman la página principal del complemento.

A la función del activador de la página principal se le pasa 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 principal.

Puedes presentar una página principal común o una específica del editor en el que el usuario abre el complemento.

Cómo mostrar la página principal común

Para mostrar la página principal común de tu complemento en los editores, incluye los campos de editor adecuados, 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 de 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": {}
  }
}

Cómo mostrar una página principal específica del editor

Para presentar una página principal específica de 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 del archivo que está abierto en la app de host de Editor.

Debes incluir el flujo de autorización de alcance drive.file para usar la función onFileScopeGrantedTrigger. Para obtener información sobre cómo solicitar el permiso drive.file, consulta Cómo solicitar acceso a archivos para el documento actual.

Cuando un usuario otorga el permiso drive.file, se activa EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Cuando se activa el activador, ejecuta la función de activador contextual que especifica el campo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction en el manifiesto del complemento.

Para 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 de host de Editor que elijas usar, por ejemplo, sheets.onFileScopeGrantedTrigger.

  1. Incluye el EDITOR_NAME.onFileScopeGrantedTrigger en la sección del editor adecuada 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 que se nombra 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 debe tener una acción adjunta y una función de devolución de llamada implementada que se ejecute cuando se haga 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 APIs de REST, por lo que se incluye onFileScopeGrantedTrigger para Hojas de cálculo de Google. Cuando un usuario otorga el permiso 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"
     }
   }

Para activar las vistas previas de vínculos de un servicio de terceros, debes configurarlas en el manifiesto de tu complemento y crear una función que devuelva una tarjeta de vista previa. En el caso de los servicios que requieren autorización del usuario, tu función también debe invocar el flujo de autorización.

Si deseas conocer los pasos para activar las vistas previas de vínculos, consulta Obtén una vista previa de los vínculos con chips inteligentes.

Objetos de eventos

Se crea un objeto de evento y se pasa a las funciones de activación, 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 construir tarjetas de complementos o controlar de otra manera su comportamiento.

La estructura completa de los objetos de evento se describe en Objetos de evento.

Cuando un editor es la app host del complemento, los objetos de evento incluyen campos de objetos de eventos de Documentos, Hojas de cálculo o Presentaciones que contienen información del cliente.

Si el complemento no tiene autorización de permiso drive.file para el usuario o el documento actuales, el objeto del evento solo contiene el campo docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission o slides.addonHasFileScopePermission. Si el complemento tiene autorización, el objeto del evento contiene todos los campos del objeto del evento de Editor.

En el siguiente ejemplo, se muestra un objeto de evento de Editor que se pasa a una función sheets.onFileScopeGrantedTrigger. Aquí, el complemento tiene la autorización de permiso drive.file para el documento actual:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }