首页

首页是一项新的 Google Workspace 插件功能，让您能够定义一张或多张非情境式卡片。非上下文卡片用于当用户在外部上下文之外显示界面，例如，当用户查看其 Gmail 收件箱时，尚未打开邮件或草稿时。

通过首页，您可以展示非情境内容，就像快速访问侧边栏 中的 Google 应用（Keep、Google 日历和 Tasks）一样。此外，首页还可以为用户提供首次打开插件时的初始起始位置，并且有助于指导新用户与插件互动。

您可以为插件定义首页，方法是在项目清单中指定插件并实现一个或多个 homepageTrigger 函数（请参阅首页配置）。

您可以有多个首页，其中每个插件对应一个扩展程序应用。您还可以决定定义一个常见默认主页，用于尚未指定自定义主页的主机。

当满足以下条件之一时，系统会显示您的插件首页：

• 首次在主机中打开插件时（授权后）。
• 用户在打开插件时从上下文上下文切换为非上下文上下文。例如，从修改日历活动到主日历。
• 用户点击返回按钮足够长的时间，使所有其他卡片从内部堆栈中弹出。
• 当非上下文卡中的界面交互导致 Navigation.popToRoot() 调用时。

设计首页并非强制性要求，但我们强烈建议您使用；如果您未定义任何首页，那么每当用户浏览到首页时，系统都会使用包含插件名称的通用卡片。

首页配置

Google Workspace 插件使用 addOns.common.homepageTrigger 字段为插件清单中的所有主机应用配置默认首页（非上下文）插件内容：

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

• runFunction：Google Workspace 插件框架为呈现首页插件卡片而调用的 Apps 脚本函数的名称。此函数是首页触发器函数。此函数必须构建并返回构成首页界面的 Card 对象的数组。如果返回多个卡片，则主机应用会在列表中显示卡片标题，以供用户选择（请参阅返回多张卡片）。

• enabled：是否应为此范围启用首页卡片。此字段是可选字段，默认值为 true。将该值设置为 false 会导致对所有主机停用首页卡片（除非该主机被替换；请参阅下文）。

注意 ：为了让主机能够使用通用首页，addOns.common.homepageTrigger 和主机的顶级资源必须存在于插件清单中。例如，如果清单中不存在 addOns.gmail，则会为 Gmail 停用 {add_ons_name_singular_short}}，且该页面将不会显示首页（或该主机中的任何其他功能）。

除了通用配置之外，每个主机应用的配置中（addOns.gmail.homepageTrigger、addOns.calendar.homepageTrigger 等）还提供了按结构相同的每个主机的替换项：

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

请注意，这相当于以下清单摘录：

    {
      ...
      "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": { /* ... */ },
        ...
      }
    }

homepageTrigger 部分都不是必需的。不过，为任何给定主机产品中的插件显示的界面，取决于是否存在相应的清单字段，以及是否存在关联的 homepageTrigger。以下示例展示了为针对不同的清单配置创建首页界面而执行的插件触发器函数（如果有）：

首页事件对象

被调用后，系统会向上述首页触发器函数 (runFunction) 传递一个包含调用上下文中的数据的事件对象。

首页事件对象不包含 widget 或上下文信息；传递的信息仅限于以下常见事件对象字段：

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale 和 commonEventObject.userTimezone（但如需了解限制信息，请参阅访问用户语言区域和时区）。

如需了解详情，请参阅事件对象。

其他非情境式卡片

您的插件界面可能包含其他并非首页的非上下文卡片。例如，您的首页可能会显示一个按钮，用于打开“设置”卡片，用户可在其中调整插件设置（在大多数情况下，这些设置独立于上下文，因此不受上下文影响）。

非上下文卡片是与任何其他卡片构建的；唯一的区别在于生成或显示卡片的操作或事件。如需详细了解如何在卡片之间创建过渡效果，请参阅导航方法。