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 proporcionar al usuario información pertinente, 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, 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 abre el complemento, este compila y devuelve una tarjeta de 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 APIs de REST, puedes incluir activadores que soliciten acceso por archivo a un documento con el alcance de drive.file. Una vez que se otorga el permiso, se ejecuta otro activador llamado EDITOR_NAME.onFileScopeGrantedTrigger y se muestra una interfaz específica para el archivo.

  • Interfaces 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 del Editor

Sigue estos pasos para compilar interfaces de complementos del Editor de compilaciones para los editores:

  1. Agrega los campos addOns.common, addOns.docs, addOns.sheets y addOns.slides correspondientes 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 de common.homepageTrigger para crear una página principal común para tus apps host.
  4. Si usas APIs de REST, implementa el flujo de autorización del 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 del 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 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 devuelva un solo Card o un array de objetos Card que conformen la página principal del complemento.

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 como la plataforma del cliente. Puedes usar los datos del objeto de evento para personalizar la construcción de la página principal.

Puedes presentar una página principal común o una página principal 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 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 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 del editor

Para presentar una página principal específica para 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 Google Sheets, puedes usar la función onFileScopeGrantedTrigger para mostrar una nueva interfaz específica del archivo que está abierto en la app host del editor.

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

Cuando un usuario otorga el alcance de drive.file, se activa EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Cuando se activa el activador, se ejecuta la función de activación contextual especificada por 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 host del 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 deseas 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 devolver 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 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.

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

Para activar las vistas previas de vínculos en un servicio de terceros, debes configurar las vistas previas de vínculos 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 quieres conocer los pasos para activar las vistas previas de vínculos, consulta Vista previa de 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 de activación usa la información del objeto de evento para determinar cómo construir tarjetas de complementos o controlar el comportamiento del complemento de otra manera.

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

Cuando un editor es la app 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 del alcance drive.file para el usuario o el documento actual, el objeto de evento solo contiene el campo 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 del 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 del alcance de drive.file para el documento actual:

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