首页

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

首页是一项新的 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.homepageTriggeraddOns.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.userLocalecommonEventObject.userTimezone(如需了解限制信息,请参阅访问用户语言区域和时区)。

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

其他非内容相关卡片

您的插件界面可以包含额外的非上下文卡片。例如,您的首页可能包含一个用于打开“设置”卡片的按钮,用户可以通过该卡片调整插件设置(在大多数情况下,这些设置独立于上下文,因此不受上下文关联)。

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