การดําเนินการส่วนกลาง

การดำเนินการส่วนกลางคือองค์ประกอบของรายการในเมนูที่อนุญาตให้ผู้ใช้เปิดหน้าเว็บใหม่ แสดงการ์ด UI ใหม่ หรือเรียกใช้ฟังก์ชัน Apps Script ที่เฉพาะเจาะจงเมื่อเลือกแล้ว ในการดำเนินการจะคล้ายกับการทำงานของการ์ดมาก เว้นแต่มีการดำเนินการทั่วไปบนการ์ดทุกใบในส่วนเสริมเสมอ ไม่ว่าบริบทของส่วนเสริมปัจจุบันจะเป็นอย่างไร

เมื่อใช้การดำเนินการทั่วไป คุณจะมั่นใจได้ว่าผู้ใช้จะเข้าถึงฟังก์ชันการทำงานบางอย่างได้เสมอไม่ว่าส่วนเสริมจะโต้ตอบกับส่วนใดก็ตาม ตัวอย่างกรณีการใช้งานสำหรับการดำเนินการส่วนกลางมีดังนี้

• เปิดหน้าเว็บการตั้งค่า (หรือแสดงการ์ดการตั้งค่า)
• แสดงข้อมูลความช่วยเหลือต่อผู้ใช้
• เริ่มต้นเวิร์กโฟลว์ใหม่ เช่น "เพิ่มลูกค้าใหม่"
• แสดงการ์ดที่ให้ผู้ใช้ส่งความคิดเห็นเกี่ยวกับส่วนเสริมได้

เมื่อใดก็ตามที่คุณมีการดำเนินการที่ไม่ได้ขึ้นอยู่กับบริบทปัจจุบัน ก็ควรทำให้การกระทำดังกล่าวเป็นการกระทำสากล

ใช้การดําเนินการแบบสากล

การดำเนินการสากลจะได้รับการกำหนดค่าในไฟล์ Manifest ของโปรเจ็กต์ส่วนเสริม เมื่อกำหนดค่าการดำเนินการส่วนกลางแล้ว ผู้ใช้ส่วนเสริมจะใช้การดำเนินการดังกล่าวได้เสมอ หากผู้ใช้กำลังดูการ์ด ชุดการดำเนินการทั่วไปที่คุณกำหนดไว้จะปรากฏในเมนูการ์ดเสมอหลังจากการทำงานของการ์ดที่คุณกำหนดไว้สำหรับการ์ดนั้น การดำเนินการส่วนกลางจะปรากฏในเมนูของการ์ดตามลำดับเดียวกับที่กำหนดไว้ในไฟล์ Manifest ของส่วนเสริม

การกำหนดค่าการดำเนินการสากล

คุณกำหนดค่าการดำเนินการสากลในไฟล์ Manifest ของส่วนเสริมได้ ดูรายละเอียดเพิ่มเติมได้ที่ไฟล์ Manifest

สำหรับการดำเนินการแต่ละรายการ คุณต้องระบุข้อความที่ควรปรากฏในเมนูสำหรับการดำเนินการนั้น จากนั้นคุณสามารถระบุช่อง openLink เพื่อระบุว่าการดำเนินการควรเปิดหน้าเว็บในแท็บใหม่โดยตรง อีกทางเลือกหนึ่งคือ ระบุช่อง runFunction ที่ระบุฟังก์ชันเรียกกลับของ Apps Script เพื่อทำงานเมื่อเลือกการดำเนินการส่วนกลาง

เมื่อใช้ runFunction ฟังก์ชันเรียกกลับที่ระบุไว้มักจะดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้

• สร้างการ์ด UI ให้แสดงทันทีโดยแสดงผลออบเจ็กต์ UniversalActionResponse ในตัว
• เปิด URL หลังจากทำงานอื่นไปแล้ว อาจเปิด URL ด้วยการส่งคืนออบเจ็กต์ UniversalActionResponse ที่สร้างขึ้น
• ดำเนินการเบื้องหลังโดยไม่เปลี่ยนไปใช้การ์ดใหม่หรือเปิด URL ในกรณีนี้ ฟังก์ชันเรียกกลับจะไม่แสดงค่าใดๆ

เมื่อเรียกใช้ ระบบจะส่งฟังก์ชันเรียกกลับผ่านออบเจ็กต์เหตุการณ์ที่มีข้อมูลเกี่ยวกับการ์ดที่เปิดอยู่และบริบทส่วนเสริม

ตัวอย่าง

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างไฟล์ Manifest ที่ตัดตอนมาสำหรับส่วนเสริมของ Google Workspace ที่ใช้การดำเนินการทั่วไปในขณะที่ขยายการใช้งาน Gmail โค้ดจะกำหนดขอบเขตข้อมูลเมตาอย่างชัดเจนเพื่อให้ส่วนเสริมกำหนดได้ว่าใครเป็นผู้ส่งข้อความ

  "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"
        }
      ]
    },
    ...
  },
  ...

การดำเนินการทั่วไป 3 อย่างที่กำหนดไว้ในตัวอย่างก่อนหน้านี้ทำสิ่งต่อไปนี้

• เปิด google.com จะเปิด https://www.google.com ในแท็บใหม่
• เปิด URL รายชื่อติดต่อจะเรียกใช้ฟังก์ชันที่กำหนด URL ที่จะเปิด แล้วเปิดในแท็บใหม่โดยใช้ออบเจ็กต์ OpenLink โค้ดจะสร้าง URL โดยใช้อีเมลของผู้ส่ง
• เปิดการตั้งค่าจะเรียกใช้ฟังก์ชัน createSettingsCards() ที่ระบุไว้ในโปรเจ็กต์สคริปต์ส่วนเสริม ฟังก์ชันนี้แสดงผลออบเจ็กต์ UniversalActionResponse ที่ถูกต้องซึ่งมีชุดการ์ดที่มีการตั้งค่าส่วนเสริมและข้อมูลอื่นๆ หลังจากฟังก์ชันสร้างออบเจ็กต์นี้เสร็จแล้ว UI จะแสดงรายการการ์ด (ดูการส่งคืนการ์ดหลายใบ)
• เรียกใช้การซิงค์เบื้องหลังจะเรียกใช้ฟังก์ชัน runBackgroundSync() ที่ระบุไว้ในโปรเจ็กต์สคริปต์ส่วนเสริม ฟังก์ชันนี้จะไม่สร้างการ์ด แต่จะทำงานในเบื้องหลังอื่นๆ ที่ไม่ได้เปลี่ยนแปลง UI เนื่องจากฟังก์ชันนี้ไม่แสดง UniversalActionResponse UI จึงไม่แสดงการ์ดใหม่เมื่อฟังก์ชันดังกล่าวเสร็จสิ้น ทั้งนี้ UI จะแสดงไอคอนหมุนของสัญญาณบอกสถานะการโหลดขณะที่ฟังก์ชันทำงานอยู่แทน

ตัวอย่างวิธีสร้างฟังก์ชัน 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.
}