首页

首页是一项新的 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.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（但如需了解限制信息，请参阅访问用户语言区域和时区）。

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

其他与情境无关的卡片

您的插件界面可能包含其他不是首页的非上下文卡片。例如，您的首页可能有一个用于打开“设置”卡片的按钮，用户可以在此调整插件设置（在大多数情况下，此类设置与上下文无关，因此不受上下文相关）。

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