Trang này được dịch bởi Cloud Translation API.

Thao tác chung

Thao tác chung là các phần tử của 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 chức năng cụ thể của Apps Script khi được chọn. Khi hoạt động, các thao tác này rất giống với thao tác thẻ, ngoại trừ việc các thao tác chung luôn được đặt trên mọi thẻ trong tiện ích bổ sung của bạn, bất kể bối cảnh của tiện ích bổ sung hiện tại là gì.

Bằng cách sử dụng các thao tác phổ biến, bạn có thể đảm bảo 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 tiện ích bổ sung nào. Dưới đây là một số ví dụ về trường hợp sử dụng đối với các thao tác 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 một thẻ cho phép người dùng gửi ý kiến phản hồi về tiện ích bổ sung.

Mỗi khi có một thao tác không phụ thuộc vào ngữ cảnh hiện tại, bạn nên cân nhắc chuyển thao tác đó thành một thao tác chung.

Sử dụng các 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 thao tác chung, người dùng tiện ích bổ sung của bạn sẽ luôn thực hiện được thao tác đó. Nếu người dùng đang xem một thẻ, thì tập hợp các thao tác chung mà bạn đã xác định sẽ luôn xuất hiện trong trình đơn thẻ, sau mọi thao tác đối với thẻ mà bạn đã xác định cho thẻ đó. Thao tác chung sẽ xuất hiện trong trình đơn thẻ theo cùng thứ tự được xác định trong tệp kê khai của tiện ích bổ sung.

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

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

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

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

Tạo 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 đã tạo.
Mở một URL (có thể là sau khi thực hiện các tác vụ khác) bằng cách trả về một đối tượng UniversalActionResponse đã tạo.
Thực hiện các thao tác ở chế độ nền mà 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 được chuyển một đối tượng sự kiện chứa thông tin về thẻ đang mở và ngữ cảnh tiện ích bổ sung.

Ví dụ:

Đoạn mã sau đây cho thấy một ví dụ về tệp kê khai trích dẫn của một Tiện ích bổ sung của Google Workspace sử dụng các thao tác phổ biến trong khi mở rộng Gmail. Mã này quy định rõ phạm vi siêu dữ liệu để tiện ích bổ sung có thể xác định ai đã gửi thông báo đang 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 thao tác phổ biến được xác định trong ví dụ trước sẽ thực hiện những việc sau:

Mở google.com sẽ mở https://www.google.com trong một thẻ mới.
URL của người liên hệ mở chạy một hàm xác định URL cần mở, sau đó mở URL đó trong thẻ mới bằng cách sử dụng đối tượng OpenLink. Mã này sẽ tạo URL bằng địa chỉ email của người gửi.
Mở phần cài đặt sẽ 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 các thẻ có chế độ cài đặt tiện ích bổ sung và các thông tin khác. Sau khi hàm hoàn tất quá trình tạo đối tượng này, giao diện người dùng sẽ hiển thị danh sách thẻ (xem phần Trả về nhiều thẻ).
Chạy tính năng đồng bộ hoá trong nền sẽ chạy hàm runBackgroundSync() được xác định trong dự án tập lệnh tiện ích 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ố tác vụ khác ở chế độ nền mà không làm 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 không hiển thị thẻ mới khi hàm này kết thúc. Thay vào đó, giao diện người dùng cho thấy một vòng quay chỉ báo đang tải trong khi hàm này đang chạy.

Dưới đây là ví dụ về cách bạn có thể tạo các hàm openContactURL(), createSettingsResponse() và 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.
}