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, 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 đã chọn. Khi hoạt động, chúng 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 hiện tại của tiện ích bổ sung.

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 chức năng nhất định, bất kể tiện ích bổ sung tương tác với phần nào với. 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.

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

Sử dụng các thao tác chung

Hành động chung được định cấu hình trong dự án của tiện ích bổ sung tệp kê khai. Sau khi định cấu hình hành động chung, tính năng này luôn khả dụng với người dùng tiện ích bổ sung của bạn. Nếu người dùng đang xem một thẻ, thì nhóm hành động chung mà bạn đã xác định sẽ luôn xuất hiện trong trình đơn thẻ, sau khi thao tác thẻ mà bạn đã xác định cho thẻ đó. Thao tác chung sẽ xuất hiện trong trình đơn thẻ ở 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 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 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 đó. hành động. Sau đó, bạn có thể chỉ định trường openLink cho biết rằng hành động sẽ mở trực tiếp một trang web trong một thẻ mới. Ngoài ra, bạn có thể chỉ định trường runFunction chỉ định 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 số 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 UniversalActionResponse .
  • 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 URL Đối tượng UniversalActionResponse.
  • 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 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 một ví dụ về tệp kê khai trích dẫn cho 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 đặt ra 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ô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 bằng một thẻ mới.
  • URL của người liên hệ mở chạy một hàm xác định URL nào cần mở sau đó mở tệp đó trong một thẻ mới bằng cách sử dụng Đối tượng OpenLink. Chiến lược phát hành đĩa đơn tạo URL bằng địa chỉ email của người gửi.
  • Mở phần cài đặt 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 giá trị hợp lệ UniversalActionResponse đối tượng chứa một bộ 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 (xem Trả nhiều thẻ).
  • Chạy tính năng đồng bộ hoá ở chế độ 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 đó 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ì không trả về một giá trị UniversalActionResponse! 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 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 openContactURL(), Hàm 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.
}