擴充訊息 UI

擴充 Gmail 的 Google Workspace 外掛程式可在使用者讀取郵件時提供使用者介面。如此一來，Google Workspace 外掛程式就能自動執行會回應訊息內容的工作，例如顯示、擷取或傳送與訊息相關的其他資訊。

存取外掛程式訊息 UI

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

這兩種情況都會導致外掛程式執行對應的情境觸發條件函式 (在外掛程式資訊清單中定義)。如果使用者在外掛程式仍處於開啟狀態時切換至其他訊息，系統也會執行觸發條件。關聯觸發函式會為該訊息建構訊息 UI，然後 Gmail 向使用者顯示該訊息。

建立訊息外掛程式

您可以遵循下列一般步驟，在外掛程式中新增訊息功能：

  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];
  }