擴充訊息 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];
  }