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ử trong 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. Trong quá trình hoạt động, chúng rất giống với thao tác trên 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, bất kể ngữ cảnh của tiện ích bổ sung hiện tại.

Bằng cách sử dụng các thao tác chung, 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 bổ sung nào của tiện ích bổ sung. Dưới đây là một số ví dụ về trường hợp sử dụng cho thao tác chung:

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ị một thẻ để người dùng có thể gửi ý kiến phản hồi về tiện ích bổ sung.

Bất cứ khi nào bạn 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 việc biến thao tác đó thành một thao tác chung.

Sử dụng thao tác chung

Các thao tác 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 có thể sử dụng 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 trên thẻ bạn đã xác định cho thẻ đó. Các thao tác chung 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 định cấu hình các thao tác 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 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 trường openLink cho biết rằng 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 trường runFunction chỉ định hàm callback Apps Script để thực thi khi thao tác chung được chọn.

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

Xây dựng thẻ giao diện người dùng để hiển thị ngay lập tức bằng cách trả về đố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 tác vụ trong 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 truyền một đối tượng sự kiện chứa thông tin về thẻ mở và ngữ cảnh tiện ích bổ sung.

Ví dụ:

Đoạn mã sau đây cho thấy một phần trích dẫn tệp kê khai mẫu cho một Tiện ích bổ sung của Google Workspace sử dụng các thao tác chung 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 thư đ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 hành động chung được xác định trong ví dụ trước có tác dụng như sau:

Thao tác Mở google.com sẽ mở ra https://www.google.com trong thẻ mới.
Tính năng 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 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 thẻ có chế độ cài đặt tiện ích bổ sung và 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 danh sách thẻ (xem phần Trả về nhiều thẻ).
Tính năng Chạy đồ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 đó nó thực hiện một số tác vụ trong nền khác 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 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 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.
}