首页

首页是 Google Workspace 插件的一项功能，可用于定义一个或多个 非上下文卡片。当用户处于特定上下文之外时（例如在查看 Gmail 收件箱时未打开邮件或草稿），非上下文卡片会显示界面。

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

如需为插件定义首页，请在 项目清单中指定首页，并实现一个或多个 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) 会传递一个 事件对象，其中包含调用上下文中的数据。

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

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

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

其他非上下文卡片

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

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