Páginas de inicio

Las páginas principales son una función de los complementos de Google Workspace que permite definir una o más tarjetas no contextuales. Las tarjetas no contextuales muestran una interfaz de usuario cuando el usuario está fuera de un contexto específico, como cuando ve su bandeja de entrada de Gmail sin un mensaje o borrador abierto.

Las páginas principales te permiten mostrar contenido no contextual, similar a las apps de Google en el panel lateral de acceso rápido (Google Keep, Calendario de Google y Google Tasks). Las páginas principales también pueden proporcionar un punto de partida inicial cuando un usuario abre tu complemento por primera vez y son útiles para enseñar a los usuarios nuevos a interactuar con él.

Para definir una página principal para tu complemento, especifícala en el manifiesto del proyecto y, luego, implementa una o más homepageTrigger funciones (consulta Configuración de la página principal).

Puedes tener varias páginas principales, una para cada aplicación host que extienda tu complemento. También puedes definir una sola página principal predeterminada común que se use en los hosts en los que no especificaste una página principal personalizada.

La página principal de tu complemento se muestra en los siguientes casos:

• Cuando el complemento se abre por primera vez en el host (después de la autorización)
• Cuando el usuario cambia de un contexto contextual a uno no contextual mientras el complemento está abierto (por ejemplo, de editar un evento del Calendario al Calendario principal)
• Cuando el usuario hace clic en el botón Atrás las veces suficientes para quitar todas las demás tarjetas de las pilas internas.
• Cuando una interacción de la IU en una tarjeta no contextual genera una Navigation.popToRoot llamada.

Se recomienda diseñar una página principal. Si no defines ninguna, se usará una tarjeta genérica que contenga el nombre del complemento cada vez que un usuario navegue a la página principal.

Configuración de la página principal

Los complementos de Google Workspace usan el campo addOns.common.homepageTrigger para configurar el contenido predeterminado (no contextual) de la página principal para las aplicaciones host en el manifiesto del complemento:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

• runFunction: Es el nombre de la función de Google Apps Script que invoca el framework de complementos de Google Workspace para renderizar las tarjetas de complementos de la página principal. Esta función es la función de activador de la página principal. Esta función debe compilar y mostrar un array de Card objetos que componen la IU de la página principal. Si se muestra más de una tarjeta, la aplicación host muestra los encabezados de las tarjetas en una lista que el usuario puede seleccionar (consulta Cómo mostrar varias tarjetas).

• enabled: Indica si las tarjetas de la página principal deben habilitarse para este alcance. Este campo es opcional y, de forma predeterminada, se establece en true. Si lo configuras como false, se inhabilitarán las tarjetas de la página principal para todos los hosts (a menos que se anule para ese host; consulta la configuración específica del host).

Para que un host use la página principal común, tanto addOns.common.homepageTrigger como el recurso de nivel superior del host deben estar presentes en el manifiesto del complemento. Por ejemplo, si addOns.gmail no está presente en el manifiesto, el complemento se inhabilita para Gmail y no mostrará una página principal ni otra funcionalidad en ese host.

Además de la configuración común, las anulaciones por host con estructura idéntica están disponibles en la configuración de cada aplicación host, en addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger y otros activadores específicos del host.

En el siguiente ejemplo, se muestra un manifiesto en el que se define un activador de página principal común, pero se anula con funciones personalizadas para Calendario y Drive, y se inhabilita para Gmail. En esta configuración, la función buildHomePage común nunca se ejecuta porque se anula o el host está inhabilitado.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

El siguiente fragmento de manifiesto es equivalente al ejemplo anterior, aunque se omiten el homepageTrigger predeterminado y la configuración de Gmail:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

No se requiere ninguna de las secciones homepageTrigger. La IU que se muestra para un complemento en un producto host depende de la presencia del campo de manifiesto correspondiente y de si hay un homepageTrigger asociado. En el siguiente ejemplo, se muestran las funciones de activador de complementos que se ejecutan para crear una IU de página principal para diferentes configuraciones de manifiesto:

Objetos de eventos de la página principal

Cuando se llama, la función de activador de la página principal (runFunction) descrita anteriormente recibe un objeto de evento que contiene datos del contexto de invocación.

Los objetos de eventos de la página principal no incluyen información contextual ni de widgets. La información que se pasa se limita a los siguientes campos de objetos de eventos comunes:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale y commonEventObject.userTimezone (consulta Cómo acceder a la configuración regional y la zona horaria del usuario para obtener información sobre las restricciones ).

Consulta Objeto de evento para obtener más detalles.

Otras tarjetas no contextuales

La IU de tu complemento puede contener tarjetas no contextuales adicionales que no sean páginas principales. Por ejemplo, tu página principal podría tener un botón que abra una tarjeta de "Configuración" para ajustar la configuración del complemento (esta configuración suele ser independiente del contexto).

Las tarjetas no contextuales se compilan como cualquier otra tarjeta. La única diferencia es qué acción o evento genera y muestra la tarjeta. Consulta Métodos de navegación para obtener detalles sobre cómo crear transiciones entre tarjetas.