首页

首页是 Google Workspace 插件的一项新功能，可让您定义一个或多个非情境卡片。非情境卡片用于在用户不在特定情境中时显示界面，例如当用户查看 Gmail 收件箱但尚未打开邮件或草稿时。

您可以在首页上显示非情境内容，就像在快捷访问侧边栏 中显示 Google 应用（Keep、日历和 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) 传递一个包含调用上下文中数据的事件对象。

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

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

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

其他非情境卡片

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

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