Páginas de inicio

Las páginas principales son una nueva función de complementos de Google Workspace que permite definir una o más tarjetas no contextuales. Las tarjetas no contextuales se usan para mostrar una interfaz de usuario cuando el usuario fuera de un contexto específico, como cuando el usuario ve su carpeta Recibidos de Gmail pero no abrió un mensaje o borrador.

Las páginas principales te permiten mostrar contenido no contextual, tal como Las apps de Google panel lateral de acceso rápido (Keep, Calendario y Tasks). Las páginas de inicio también pueden brindar cuando un usuario abra tu complemento por primera vez y son útiles para enseñar a los usuarios nuevos a interactuar con el complemento.

Puedes definir una página principal para tu complemento especificándola en tu proyecto e implementar una o más funciones homepageTrigger (consulta Configuración de la página principal).

Puedes tener varias páginas principales, una para cada aplicación host que tu complemento se extiende. También puedes decidir definir una única página de inicio predeterminada común que usarse en hosts en los que no especificaste una página principal personalizada.

La página principal de tu complemento se muestra cuando se cumple una de las siguientes condiciones:

• 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, desde editar un evento de calendario del Calendario principal.
• Cuando el usuario hace clic en el botón Atrás varias veces quita 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.

Diseñar una página de inicio no es obligatorio, pero es muy recomendable. Si no defines ninguna, se incluirá una tarjeta genérica que contiene el nombre de tu complemento se utiliza cuando un usuario navega de otra forma a la página de inicio.

Configuración de la página principal

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

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

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

• enabled: Indica si se deben habilitar las tarjetas de la página principal para este alcance. Esta es opcional y el valor predeterminado es true. Establecer esto en false causa las tarjetas de la página principal se inhabilitarán para todos los hosts (a menos que se anulen para eso host; consulta a continuación).

Nota: Para que un host use la página principal común, deben addOns.common.homepageTrigger y el recurso de nivel superior del host debe estar presente en el complemento manifiesto. Por ejemplo, addOns.gmail no está presente en el manifiesto, entonces el complemento se inhabilita para Gmail y No mostrará una página principal (ni ninguna otra funcionalidad en ese host).

Además de la configuración común, también hay anulaciones por host idénticamente estructuradas en las propiedades de configuración, a la(s) addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger, etcétera:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

Ten en cuenta que esto equivale al siguiente extracto de manifiesto:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

Ninguna de las homepageTrigger secciones es obligatoria. Sin embargo, la IU que se muestra para un complemento en cualquier producto host depende de la presencia del campo de manifiesto correspondiente y si hay un elemento homepageTrigger En el siguiente ejemplo, se muestra qué funciones de activación de complementos se ejecutan (si hay alguno) para crear una IU de página de inicio para diferentes manifiestos parámetros de configuración:

Objetos de eventos de la página principal

Cuando se la llama, la función de activación de la página principal (runFunction) descrita anteriormente es Pasaron 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. el que se pasa se limita a la siguiente objeto de evento común campos:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale y commonEventObject.userTimezone (pero 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 son las páginas principales. Por ejemplo, tu página principal podría tener un botón que abre una “Configuración” tarjeta en la que el usuario puede ajustar la configuración de los complementos (como los parámetros en la mayoría de los casos, sería independiente del contexto y, por lo tanto, no sería contextual).

Las tarjetas no contextuales se crean 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.