首页

首页是 Google Workspace 加购服务的一项功能，可用于定义一个或多个非情境化卡片。非情境化卡片会在用户处于特定情境之外时显示用户界面，例如在查看 Gmail 收件箱时未打开任何邮件或草稿。

借助首页，您可以显示非情境相关的内容，类似于快速访问侧边栏（Google Keep、Google 日历和 Google Tasks）中的 Google 应用。首页还可以在用户首次打开插件时提供初始起点，并且有助于教导新用户如何与插件互动。

通过在项目清单中指定插件的主页并实现一个或多个 homepageTrigger 函数来定义插件的主页（请参阅主页配置）。

您可以拥有多个首页，每个首页对应一个插件所扩展的宿主应用。您还可以定义一个通用默认首页，用于未指定自定义首页的主机。

在以下情况下，系统会显示插件首页：

  • 首次在宿主中打开插件时（获得授权后）。
  • 当用户在插件处于打开状态时从情境化上下文切换到非情境化上下文时。例如，从修改日历活动切换到主日历。
  • 当用户点击返回按钮的次数足以从内部堆栈中弹出所有其他卡片时。
  • 当非情境卡片中的界面互动导致 Navigation.popToRoot 调用时。

建议设计首页。如果您未定义任何卡片，则每当用户前往首页时，系统都会使用包含插件名称的通用卡片。

首页配置

Google Workspace 插件使用 addOns.common.homepageTrigger 字段在插件清单中为宿主应用配置默认首页（非情境化）插件内容：

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

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

  • enabled：是否应针对相应范围启用首页卡片。此字段是可选字段，默认值为 true。将此属性设置为 false 会导致所有主机的首页卡片都被停用（除非为相应主机替换了此设置；请参阅特定于主机的配置）。

如需让宿主使用通用首页，插件清单中必须同时包含 addOns.common.homepageTrigger 和宿主的顶级资源。例如，如果清单中没有 addOns.gmail，则该插件在 Gmail 中处于停用状态，并且不会在该宿主中显示首页或其他功能。

除了通用配置之外，每个宿主应用的配置中还提供了结构相同的按宿主替换项，位于 addOns.gmail.homepageTrigger、addOns.calendar.homepageTrigger 和其他宿主专用触发器中。

以下示例展示了一个清单，其中定义了常见的首页触发器，但该触发器被替换为日历和云端硬盘的自定义函数，并针对 Gmail 停用。在此配置中，通用 buildHomePage 函数永远不会执行，因为该函数已被替换或主机已被停用。

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

以下清单摘录与上一个示例等效，即使省略了默认 homepageTrigger 和 Gmail 配置也是如此：

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

所有 homepageTrigger 部分都不是必需的。主机产品中显示的插件界面取决于是否存在相应的清单字段以及是否存在关联的 homepageTrigger。以下示例展示了在不同清单配置下，哪些插件触发器函数会执行以创建首页界面：

示意图：显示了插件首页触发器函数执行流程

首页活动对象

调用时，前面介绍的主页触发器函数 (runFunction) 会传递一个包含调用上下文数据的事件对象。

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

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

如需了解详情，请参阅活动对象。

其他非情境化卡片

插件界面可以包含其他非上下文相关的卡片，这些卡片不是首页。例如，您的首页可能有一个按钮，用于打开“设置”卡片以调整插件设置（此类设置通常独立于上下文）。

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