扩展消息界面

扩展 Gmail 的 Google Workspace 加购项可以在用户阅读邮件时提供界面。这样一来，Google Workspace 加载项便可自动执行响应消息内容的任务，例如显示、检索或发送与消息相关的其他信息。

访问加购项消息界面

您可以通过两种方式查看插件的消息界面。第一种方式是在插件已打开的情况下打开邮件（例如，在 Gmail 收件箱窗口中查看插件首页时）。第二种方法是在查看邮件时启动该插件。

无论哪种情况，都会导致插件执行插件清单中定义的相应上下文触发函数。如果用户在插件仍处于打开状态时切换到其他邮件，该触发器也会执行。上下文触发函数会为相应邮件构建消息界面，然后 Gmail 会向用户显示该界面。

构建消息插件

您可以按照以下常规步骤向插件添加消息功能：

1. 向插件脚本项目的清单添加适当的字段，包括消息功能所需的范围。请务必向清单添加条件触发字段，并将 unconditional 值设置为 {}。
2. 实现一个情境触发函数，当用户在消息中选择插件时，该函数会构建消息界面。
3. 实现响应用户界面互动所需的关联函数。

情境触发器

为了在用户阅读邮件时提供帮助，Google Workspace 加载项可以在其清单中定义情境触发器。当用户打开符合触发条件*的 Gmail 邮件（插件处于打开状态）时，触发器会触发。触发器触发后，会执行一个情境化触发器函数，该函数会构建插件界面并将其返回给 Gmail 以供显示。此时，用户可以开始与之互动。

上下文触发器在插件的项目清单中定义。 触发器定义会告知 Gmail 在哪些条件下触发哪个触发器函数。例如，以下清单代码段设置了一个无条件触发器，用于在打开消息时调用触发器函数 onGmailMessageOpen()：

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

目前，唯一可用的情境触发器类型是 unconditional，它会针对所有电子邮件触发，无论内容如何。

情境化触发函数

每个情境化触发器都必须有一个相应的触发器函数，用于构建插件的用户界面。您可以在清单的 onTriggerFunction 字段中指定此函数。您需要实现此函数，以接受操作事件对象实参，并返回单个 Card 对象或 Card 对象数组。

当特定 Gmail 邮件的上下文触发器触发时，系统会调用此函数并向其传递一个操作事件对象。触发函数通常使用此事件对象提供的消息 ID，通过 Apps 脚本的 Gmail 服务获取消息文本和其他详细信息。例如，触发函数可以使用以下函数提取消息内容：

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

注意： 在大多数情况下，您必须先使用事件对象和 GmailApp.setCurrentMessageAccessToken(accessToken) 函数提供的访问令牌激活 Gmail 范围，然后才能使用其他 Gmail 服务函数。

然后，触发函数可以根据此数据采取行动，提取界面所需的信息。例如，一个可总结销售额的插件可以从邮件正文中收集销售数据，并整理这些数据以在卡片中显示。

触发函数必须构建并返回一个已构建的 Card 对象数组。例如，以下代码构建了一个插件，其中包含一张仅列出邮件主题和发件人的卡片：

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }