扩展消息界面

用于扩展 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 脚本的 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];
  }