การทำงานส่วนกลางคือองค์ประกอบของรายการในเมนูที่อนุญาตให้ผู้ใช้เปิดหน้าใหม่ แสดงการ์ด UI ใหม่ หรือเรียกใช้ฟังก์ชัน Apps Script เฉพาะเมื่อ ที่เลือกไว้ ในการใช้งานจริงจะคล้ายกันมาก การทำงานของการ์ด เว้นแต่ว่าการดำเนินการสากลจะอยู่ในการ์ดทุกใบในส่วนเสริม โดยไม่คำนึงถึงบริบทส่วนเสริมปัจจุบัน
เมื่อใช้การดำเนินการแบบสากล คุณจะมั่นใจได้ว่าผู้ใช้จะเข้าถึง ฟังก์ชันการทำงานบางอย่าง โดยไม่คำนึงถึงส่วนใดของส่วนเสริม ด้วย ต่อไปนี้เป็นตัวอย่างกรณีการใช้งานสำหรับการดำเนินการสากล
- เปิดหน้าเว็บการตั้งค่า (หรือแสดงการ์ดการตั้งค่า)
- แสดงข้อมูลความช่วยเหลือแก่ผู้ใช้
- เริ่มเวิร์กโฟลว์ใหม่ เช่น "เพิ่มลูกค้าใหม่"
- แสดงการ์ดที่อนุญาตให้ผู้ใช้ส่งความคิดเห็นเกี่ยวกับส่วนเสริม
เมื่อใดก็ตามที่คุณดำเนินการ ที่ไม่เกี่ยวข้องกับบริบทในปัจจุบัน คุณควรพิจารณาให้การดำเนินการ เป็นสากล
ใช้การดำเนินการสากล
กำหนดค่าการดำเนินการสากลในโปรเจ็กต์ของส่วนเสริมแล้ว ประจักษ์แจ้ง เมื่อคุณกำหนดค่า การดำเนินการสากล ส่วนขยายจะพร้อมใช้งานเสมอสำหรับผู้ใช้ส่วนเสริมของคุณ หากผู้ใช้ กำลังดูการ์ด ชุดการทำงานสากลที่คุณกำหนดไว้จะปรากฏขึ้นเสมอ ในเมนูการ์ด หลัง การดำเนินการกับการ์ด ที่คุณกำหนดไว้สำหรับบัตรนั้น การทำงานส่วนกลางจะปรากฏในเมนูการ์ดใน ลำดับเดียวกับที่กำหนดไว้ในไฟล์ Manifest ของส่วนเสริม
การกำหนดค่าการทำงานสากล
คุณกำหนดค่าการดำเนินการส่วนกลางในไฟล์ Manifest ของส่วนเสริม ดู ไฟล์ Manifest เพื่อดูรายละเอียดเพิ่มเติม
สำหรับการดำเนินการแต่ละอย่าง คุณต้องระบุข้อความที่ควรปรากฏในเมนูของการดำเนินการดังกล่าว
การดำเนินการ จากนั้นคุณสามารถระบุช่อง openLink
ที่ระบุว่าการดำเนินการดังกล่าว
ระบบจะเปิดหน้าเว็บในแท็บใหม่โดยตรง อีกทางเลือกหนึ่งคือ คุณสามารถระบุ
ฟิลด์ runFunction
ที่ระบุฟังก์ชัน Callback ของ Apps Script สำหรับ
ดำเนินการเมื่อเลือกการดำเนินการสากล
เมื่อใช้ runFunction
ฟังก์ชัน Callback ที่ระบุมักจะดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้
ดังต่อไปนี้
- สร้างการ์ด UI เพื่อแสดงทันทีโดยแสดงผล
UniversalActionResponse
ออบเจ็กต์ - เปิด URL อาจหลังจากทำงานอื่นๆ ไปแล้วด้วยการส่งคืน
ออบเจ็กต์
UniversalActionResponse
รายการ - ทำงานในเบื้องหลังโดยไม่เปลี่ยนไปใช้การ์ดใหม่หรือเปิด URL ในกรณีนี้ ฟังก์ชัน Callback จะไม่แสดงผลใดๆ
เมื่อเรียกใช้ ฟังก์ชัน Callback จะส่งแท็ก ออบเจ็กต์เหตุการณ์ ที่มีข้อมูลเกี่ยวกับการ์ดแบบเปิดและบริบทส่วนเสริม
ตัวอย่าง
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างข้อความ 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.
}