构建 Google 云端硬盘界面

Google Workspace 插件可以在用户使用 Google 云端硬盘时提供自定义界面。这样,您就可以为用户提供更多相关信息、自动执行任务,并将第三方系统连接到 Google 云端硬盘。

访问插件界面

如果 Google Workspace 插件的图标显示在云端硬盘界面右侧的图标列中,您就可以在 Google 云端硬盘中打开该插件。Google Workspace 插件可以定义主页界面和/或内容选择界面:

  • 如果用户在 Google 云端硬盘中点击该插件图标,该插件会执行相应的 drive.homepageTrigger 函数(如果存在)。此函数会构建首页卡片并将其返回到 Google 云端硬盘以供展示。如果未定义 drive.homepageTrigger 函数,则会显示通用首页卡片。
  • 如果用户在 Google 云端硬盘中选择一项或多项内容,然后点击插件图标,或在插件打开时选择内容,则插件会执行相应的 drive.onItemsSelectedTrigger 上下文函数(如果存在)。此函数会构建插件的 Google 云端硬盘上下文“已选择的内容”界面,并将其返回到 Google 云端硬盘以供显示。

构建云端硬盘插件界面

您可以按照以下常规步骤构建用于扩展 Google 云端硬盘的接口:

  1. 确定您是否希望插件具有云端硬盘专用的首页。另外,您还需要决定是否要在用户选择云端硬盘内容时提供上下文界面。
  2. 在插件脚本项目清单中添加相应的 addOns.commonaddOns.drive 字段,包括所需的任何云端硬盘范围
  3. 如果您要提供云端硬盘专用首页,请实现 drive.homepageTrigger 函数来构建此界面。您还可以选择为多个 Google Workspace 主机使用 common.homepageTrigger 接口。
  4. 如果您要提供云端硬盘上下文项选择界面,则必须实现 drive.onItemsSelectedTrigger 上下文触发器函数才能构建此接口。如需了解详情,请参阅所选项的云端硬盘上下文界面
  5. 实现响应用户的界面互动(例如按钮点击)所需的关联回调函数。

云端硬盘首页

Google 云端硬盘支持显示 Google Workspace 插件首页。如需在 Google 云端硬盘中显示插件的常用首页,只需确保插件清单中有 addOns.drive 字段即可。

或者,将 drive.homepageTrigger 添加到插件清单中,以提供云端硬盘专用首页。

无论是哪种情况,您都必须在插件的脚本项目中提供首页触发器函数的名称。在需要时,系统会自动调用此函数来构建云端硬盘首页。您必须实现此函数才能构建并返回单个 Card 或构成首页的 Card 对象数组。系统会向首页触发器函数传递一个事件对象作为参数,其中包含一些常规信息(例如客户端的平台)。您可以使用事件对象数据来定制首页的构建方式。

所选项的云端硬盘上下文界面

Google 云端硬盘依靠上下文触发器来确定当用户选择一项或多项 Google 云端硬盘内容时要显示的界面(如果有)。当触发器触发时,它会执行插件清单中的 drive.onItemsSelectedTrigger.runFunction 字段指定的上下文触发器函数。

如需为云端硬盘创建上下文内容选择界面,您必须执行以下操作:

  1. 确保插件的清单包含 https://www.googleapis.com/auth/drive.addons.metadata.readonly 范围

  2. 确保清单包含 drive.onItemsSelectedTrigger 部分。

  3. 实现 drive.onItemsSelectedTrigger 字段中指定的函数。此函数接受事件对象作为参数,并且必须返回单个 Card 对象或 Card 对象的数组。

  4. 与任何卡片一样,您必须实现任何用于为接口提供 widget 交互性的回调函数。例如,如果您在界面中添加一个按钮,则该按钮应附加一个 Action,并且应实现一个在点击该按钮时运行的回调函数。

事件对象

系统会创建一个事件对象,并将其传递给 drive.homepageTriggerdrive.onItemsSelectedTrigger 触发函数(在调用这些函数时)。触发器函数可以使用此事件对象中的信息来确定如何构建插件卡或以其他方式控制插件行为。

事件对象中介绍了事件对象的完整结构。当云端硬盘是插件的执行主机应用时,上下文事件对象会包含包含云端硬盘专属客户端信息的云端硬盘事件对象字段。

内容选择触发器的上下文云端硬盘事件对象包含在触发器触发时用户选择的内容的相关信息。当用户在云端硬盘中选择多项内容时,其中一项被视为主要兴趣项之一;该项称为“活动光标项”。

以下示例展示了传递给 drive.onItemsSelectedTrigger 函数的云端硬盘事件对象

    {
      "commonEventObject": { ... },
      "drive": {
        "activeCursorItem":{
          "addonHasFileScopePermission": true,
          "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
          "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
          "mimeType":"application/pdf",
          "title":"How to get started with Drive"
        },
        "selectedItems": [
          {
            "addonHasFileScopePermission": true,
            "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
            "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
            "mimeType":"application/pdf",
            "title":"How to get started with Drive"
          },
          ...
        ]
      },
      ...
    }