首页

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

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

其他与内容无关的卡片

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

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