擴充訊息 UI

擴充 Gmail 的 Google Workspace 外掛程式可以在使用者閱讀郵件時提供使用者介面。這項設定可讓 Google Workspace 外掛程式自動執行與郵件內容相關的工作，例如顯示、擷取或傳送與郵件相關的其他資訊。

存取外掛程式訊息使用者介面

查看外掛程式訊息 UI 的方法有兩種。第一種方法是開啟郵件，同時開啟外掛程式 (例如在 Gmail 收件匣視窗中查看外掛程式首頁時)。第二種方式是在查看郵件時啟動外掛程式。

無論是哪一種情況，外掛程式都會執行外掛程式資訊清單中定義的相應情境觸發函式。如果使用者在外掛程式仍處於開啟狀態時切換至其他郵件，也會觸發執行動作。內容比對觸發函式會為該郵件建構訊息 UI，然後 Gmail 會向使用者顯示該 UI。

建構訊息外掛程式

如要為外掛程式新增訊息功能，請按照下列一般步驟操作：

  1. 在外掛程式指令碼專案的資訊清單中新增適當的欄位，包括訊息功能所需的範圍。請務必在資訊清單中新增條件式觸發欄位，並將 unconditional 值設為 {}。
  2. 實作情境觸發函式，在使用者於訊息中選取外掛程式時，建構訊息 UI。
  3. 實作回應使用者 UI 互動所需的相關函式。

情境觸發條件

如要在使用者閱讀郵件時提供協助，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];
  }