扩展消息界面

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

访问插件消息界面

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

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

构建消息插件

您可以按照以下一般步骤为插件添加消息功能：

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

内容相关触发器

为了在用户阅读邮件时为其提供帮助，Google Workspace 插件可以在其清单中定义情境触发器。当用户打开符合触发器条件的 Gmail 邮件（同时打开该插件）时，触发器会触发*。触发的触发器会执行上下文触发器函数，该函数会构建插件界面并将其返回以供 Gmail 显示。此时，用户可以开始与应用互动。

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

{
  ...
  "addOns": {

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

情境触发器函数

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

当针对给定 Gmail 邮件触发内容相关触发器时，该触发器会调用此函数并将操作事件对象传递给它。通常，触发器函数会使用此事件对象提供的消息 ID，通过 Apps Script 的 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();

然后，触发器函数可以根据这些数据执行操作，提取界面所需的信息。例如，用于汇总销售数据的插件可以从消息正文中收集销售数据，并对其进行整理，以便在卡片中显示。

触发器函数必须构建并返回一个已构建的 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];
  }