扩展消息界面

扩展 Gmail 的 Google Workspace 插件 显示用户阅读消息的界面这样, 用于自动执行任务的 Google Workspace 插件 例如显示、检索或发出 与邮件有关的其他信息。

访问插件消息界面

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

无论哪种情况,该插件都会执行相应的 上下文触发器函数,在 插件清单。 如果用户在 插件仍处于打开状态。上下文触发器函数会构建用于 Gmail 随后会将其显示给用户。

构建消息插件

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

  1. 向插件脚本项目添加适当的字段 manifest, 包括 所需的作用域 消息功能请务必向代码中添加 条件触发器字段 添加到清单 unconditional 的值为 {}
  2. 实现用于构建消息界面的上下文触发器函数 当用户在消息中选择该插件时触发。
  3. 实现响应用户界面所需的关联函数 互动。

上下文触发器

为了在阅读邮件时为用户提供帮助, Google Workspace 插件可以定义 上下文触发器。当用户 打开符合触发器的 Gmail 邮件(在打开插件的情况下) 条件*,则会触发触发器。触发的触发器执行 上下文触发器函数,用于构造 插件界面,并返回该界面供 Gmail 显示。此时, 用户就可以开始与其互动了

已在插件的项目中定义上下文触发器 manifest 的文件。 触发器定义会告知 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];
  }