首页

首页是一项新的 Google Workspace 插件功能 让您能够定义一张或多张与内容不相关的卡片。 非内容相关卡片用于在用户 在特定上下文之外,例如当用户查看 Gmail 收件箱时 但尚未打开邮件或草稿。

通过首页,您可以展示不相关的内容,就像 Google Apps 可快速访问侧边栏 (Keep、日历和 Tasks)。首页还可以提供初始启动 在用户首次打开插件时显示,对于教学活动非常有用 以及如何与您的插件互动的新用户。

您可以通过在项目中指定插件来为其定义主页 清单并实现一个或多个 homepageTrigger 函数(请参阅 首页配置)。

您可以有多个主页,每个主页对应于您的插件的每个托管应用 扩展。您也可以定义一个通用的默认主页,即 在您尚未指定自定义主页的主机中使用。

当满足以下条件之一时,系统会显示您的插件首页:

  • 插件首次在主机中打开(授权后)时。
  • 当用户从上下文上下文切换到非上下文上下文时 。例如,从编辑日历活动到 主日历。
  • 当用户点击返回按钮的次数足够多时 从内部堆栈中逐出其他卡片
  • 当非上下文卡片中的界面互动导致 Navigation.popToRoot() 调用。

设计首页不是必需的,但强烈建议进行设计;如果您没有定义任何字段,则通用卡片 只要用户以其他方式浏览了 首页。

首页配置

Google Workspace 插件使用 addOns.common.homepageTrigger 字段以配置默认首页(非上下文)插件内容, 插件中的所有主机应用 manifest

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }
  • runFunction:用于执行测试的 Apps 脚本函数的名称 Google Workspace 插件框架会调用,以呈现首页插件卡片。 此函数即为首页触发器函数。此函数必须构建 然后返回一个包含Card的数组 组成主页界面的对象。如果返回了多张卡片, 托管应用以列表形式显示卡片标题,用户可选择 来源(请参阅 返回多张卡片)。

  • enabled:是否应为此范围启用首页卡片。这个 字段是可选字段,默认值为 true。将此设置为 false 会导致 将针对所有主机停用首页卡片(除非针对该卡片进行替换) host;请参见下文)。

除了通用配置,还有 结构相同的每个主机替换项可在每个主机应用的 配置,位于 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(但 请参阅访问用户语言区域和时区 获取限制信息)。

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

其他与内容无关的卡片

您的插件界面中可以包含未与内容相关的其他卡片, 首页例如,您的首页上可能有一个按钮 “设置”在该卡片中,用户可以调整插件设置 多数情况下与情境无关,因此与情境无关)。

非内容相关卡片的制作方式与其他卡片相同;唯一的区别是 哪些操作或事件会生成并显示该卡片。请参阅 导航方法 ,详细了解如何在卡片之间创建转场效果。