扩展消息界面

Google Workspace 扩展 Gmail 的插件可以在用户阅读邮件时提供界面。这样,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];
  }