Thao tác chung

Thao tác chung là các phần tử mục trong trình đơn cho phép người dùng mở một trang web mới, hiển thị thẻ giao diện người dùng mới hoặc chạy một hàm Apps Script cụ thể khi được chọn. Khi hoạt động, các thao tác này rất giống với thao tác trên thẻ, ngoại trừ thao tác chung luôn được đặt trên mọi thẻ trong tiện ích bổ sung, bất kể ngữ cảnh hiện tại của tiện ích bổ sung đó là gì.

Bằng cách sử dụng các hành động chung, bạn có thể đảm bảo rằng người dùng luôn có quyền truy cập vào một số chức năng, bất kể họ tương tác với phần bổ sung nào. Dưới đây là một số ví dụ về các trường hợp sử dụng cho các hành động phổ biến:

  • Mở trang web cài đặt (hoặc hiển thị thẻ cài đặt).
  • Hiển thị thông tin trợ giúp cho người dùng.
  • Bắt đầu một quy trình công việc mới, chẳng hạn như "Thêm khách hàng mới".
  • Hiển thị thẻ cho phép người dùng gửi phản hồi về tiện ích bổ sung.

Bất cứ khi nào có một hành động không phụ thuộc vào ngữ cảnh hiện tại, bạn nên xem xét việc biến nó thành một hành động chung.

Sử dụng thao tác chung

Hành động chung được định cấu hình trong tệp kê khai dự án của tiện ích bổ sung. Sau khi bạn định cấu hình một hành động chung, người dùng tiện ích bổ sung của bạn sẽ luôn có thể thực hiện hành động đó. Nếu người dùng đang xem thẻ, nhóm hành động chung mà bạn đã xác định luôn xuất hiện trong trình đơn thẻ, sau mọi hành động thẻ bạn đã xác định cho thẻ đó. Các thao tác chung sẽ xuất hiện trong trình đơn thẻ theo cùng thứ tự mà chúng được xác định trong tệp kê khai của tiện ích bổ sung.

Định cấu hình thao tác chung

Bạn định cấu hình các hành động chung trong tệp kê khai của tiện ích bổ sung; xem Tệp kê khai để biết thêm thông tin chi tiết.

Đối với mỗi hành động, bạn chỉ định văn bản sẽ xuất hiện trong trình đơn cho hành động đó. Sau đó, bạn có thể chỉ định trường openLink để cho biết thao tác đó sẽ mở trực tiếp một trang web trong thẻ mới. Ngoài ra, bạn có thể chỉ định trường runFunction để chỉ định hàm gọi lại Apps Script để thực thi khi thao tác chung được chọn.

Khi runFunction được sử dụng, hàm callback được chỉ định thường thực hiện một trong những thao tác sau:

  • Xây dựng các thẻ giao diện người dùng để hiển thị ngay lập tức bằng cách trả về một đối tượng UniversalActionResponse được tạo.
  • Mở một URL, có thể là sau khi thực hiện các thao tác khác bằng cách trả về một đối tượng UniversalActionResponse được tạo.
  • Thực hiện các tác vụ trong nền không chuyển sang thẻ mới hoặc mở URL. Trong trường hợp này, hàm callback không trả về giá trị nào.

Khi được gọi, hàm callback sẽ được truyền một đối tượng sự kiện chứa thông tin về thẻ đang mở và ngữ cảnh của tiện ích bổ sung.

Ví dụ:

Đoạn mã sau đây cho thấy đoạn trích mẫu của tệp kê khai cho Google Workspace tiện ích bổ sung sử dụng các thao tác phổ biến trong khi mở rộng Gmail. Mã này đặt phạm vi siêu dữ liệu một cách rõ ràng để tiện ích bổ sung có thể xác định ai đã gửi tin nhắn mở.

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

Ba hành động phổ biến được xác định trong ví dụ trước thực hiện như sau:

  • Mở google.com sẽ mở trang https://www.google.com trong một thẻ mới.
  • Mở URL liên hệ chạy một hàm xác định URL cần mở, sau đó mở URL đó trong một thẻ mới bằng cách sử dụng đối tượng OpenLink. Mã này sẽ xây dựng URL bằng địa chỉ email của người gửi.
  • Open settings (Cài đặt mở) chạy hàm createSettingsCards() được xác định trong dự án tập lệnh tiện ích bổ sung. Hàm này trả về một đối tượng UniversalActionResponse hợp lệ chứa một tập hợp thẻ có chế độ cài đặt tiện ích bổ sung và các thông tin khác. Sau khi hàm tạo xong đối tượng này, giao diện người dùng sẽ hiển thị danh sách các thẻ (xem phần Trả về nhiều thẻ).
  • Chạy tính năng đồng bộ hoá trong nền chạy hàm runBackgroundSync() được xác định trong dự án tập lệnh bổ sung. Hàm này không tạo thẻ; thay vào đó, hàm này thực hiện một số thao tác trong nền khác mà không thay đổi giao diện người dùng. Vì hàm không trả về UniversalActionResponse, nên giao diện người dùng sẽ không hiển thị thẻ mới khi hàm kết thúc. Thay vào đó, giao diện người dùng sẽ hiển thị một trình đơn chỉ báo đang tải trong khi hàm đang chạy.

Dưới đây là ví dụ về cách bạn có thể tạo hàm openContactURL(), createSettingsResponse()runBackgroundSync():

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}