วิดเจ็ตการป้อนข้อความช่วยให้ส่วนเสริมอ่านและโต้ตอบกับข้อความที่ผู้ใช้ให้ไว้ได้ คุณสามารถกำหนดค่าวิดเจ็ตเหล่านี้เพื่อให้คำแนะนำสำหรับป้อนข้อความอัตโนมัติแก่ผู้ใช้ได้
คำแนะนำที่ระบุอาจมาจากรายการสตริงแบบคงที่ที่คุณระบุ หรือจะสร้างคำแนะนำจากบริบทก็ได้ เช่น ข้อความที่ผู้ใช้พิมพ์ลงในวิดเจ็ตแล้ว
การกำหนดค่าคำแนะนำ
การกำหนดค่าคำแนะนำสำหรับการป้อนข้อความต้องการให้คุณทำสิ่งต่อไปนี้เท่านั้น
- สร้างรายการคำแนะนำโดยทำดังนี้
- การสร้างรายการแบบคงที่และ/หรือ
- กำหนดการดำเนินการด้วยฟังก์ชัน Callback ที่สร้างรายการแบบไดนามิกจากบริบท
- แนบรายการคำแนะนำและ/หรือการดำเนินการเข้ากับวิดเจ็ตการป้อนข้อความ
หากคุณระบุทั้งรายการคำแนะนำและการดำเนินการแบบคงที่ UI แอปพลิเคชันจะใช้รายการแบบคงที่จนกว่าผู้ใช้จะเริ่มป้อนอักขระ โดยระบบจะใช้ฟังก์ชัน Callback และระบบจะไม่สนใจรายการแบบคงที่
คำแนะนำแบบคงที่
หากต้องการเสนอรายการคำแนะนำแบบคงที่ คุณเพียงแค่ต้องดำเนินการดังนี้
- สร้างออบเจ็กต์
Suggestions
- เพิ่มคำแนะนำแบบคงที่แต่ละรายการโดยใช้
addSuggestion()
หรือaddSuggestions()
- แนบออบเจ็กต์
Suggestions
กับวิดเจ็ตโดยใช้TextInput.setSuggestions()
UI จะแสดงคำแนะนำแบบคงที่ตามลำดับการเพิ่ม นอกจากนี้ UI ยังจับคู่คำนำหน้าที่ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่โดยอัตโนมัติ และกรองรายการคำแนะนำเมื่อผู้ใช้พิมพ์อักขระลงในวิดเจ็ต
การดำเนินการตามคำแนะนำ
หากไม่ได้ใช้รายการคำแนะนำแบบคงที่ คุณต้องกำหนดการดำเนินการเพื่อสร้างคำแนะนำแบบไดนามิก โดยทำตามขั้นตอนต่อไปนี้
- สร้างออบเจ็กต์
Action
และเชื่อมโยงกับฟังก์ชัน Callback ที่คุณกำหนด - เรียกใช้ฟังก์ชัน
TextInput.setSuggestionsAction()
ของวิดเจ็ตโดยให้มีออบเจ็กต์Action
- ใช้ฟังก์ชัน Callback เพื่อสร้างรายการคำแนะนำและแสดงผลออบเจ็กต์
SuggestionsResponse
ที่สร้างขึ้น
UI จะเรียกฟังก์ชัน Callback เมื่อใดก็ตามที่ผู้ใช้พิมพ์อักขระลงในการป้อนข้อความ แต่เมื่อผู้ใช้หยุดพิมพ์ไปชั่วขณะหนึ่งเท่านั้น ฟังก์ชัน Callback จะได้รับออบเจ็กต์เหตุการณ์ที่มีข้อมูลเกี่ยวกับวิดเจ็ตของการ์ดที่เปิดอยู่ ดูรายละเอียดได้ที่ออบเจ็กต์เหตุการณ์การดำเนินการ
ฟังก์ชัน Callback ต้องแสดงผลออบเจ็กต์ SuggestionsResponse
ที่ถูกต้องซึ่งมีรายการคำแนะนำที่จะแสดง UI จะแสดงคำแนะนำ
ตามลำดับที่เพิ่ม UI จะไม่กรองคำแนะนำ Callback อัตโนมัติตามอินพุตของผู้ใช้ ซึ่งต่างจากรายการแบบคงที่ หากต้องการใช้ตัวกรองดังกล่าว คุณต้องอ่านค่าการป้อนข้อความจากออบเจ็กต์เหตุการณ์และกรองคำแนะนำขณะที่สร้างรายการ
ตัวอย่าง
ข้อมูลโค้ดส่วนเสริมของ Google Workspace ต่อไปนี้แสดงวิธีกำหนดค่าคำแนะนำในวิดเจ็ตการป้อนข้อความที่แตกต่างกัน 2 วิดเจ็ต โดยรายการแรกมีรายการแบบคงที่ และอันแรกใช้ฟังก์ชัน Callback
// Create an input with a static suggestion list.
var textInput1 = CardService.newTextInput()
.setFieldName('colorInput')
.setTitle('Color choice')
.setSuggestions(CardService.newSuggestions()
.addSuggestion('Red')
.addSuggestion('Yellow')
.addSuggestions(['Blue', 'Black', 'Green']));
// Create an input with a dynamic suggestion list.
var action = CardService.newAction()
.setFunctionName('refreshSuggestions');
var textInput2 = CardService.newTextInput()
.setFieldName('emailInput')
.setTitle('Email')
.setSuggestionsAction(action);
// ...
/**
* Build and return a suggestion response. In this case, the suggestions
* are a list of emails taken from the To: and CC: lists of the open
* message in Gmail, filtered by the text that the user has already
* entered. This method assumes the Google Workspace
* add-on extends Gmail; the add-on only calls this method for cards
* displayed when the user has entered a message context.
*
* @param {Object} e the event object containing data associated with
* this text input widget.
* @return {SuggestionsResponse}
*/
function refreshSuggestions(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);
var userInput = e && e.formInput['emailInput'].toLowerCase();
var messageId = e.gmail.messageId;
var message = GmailApp.getMessageById(messageId);
// Combine the comma-separated returned by these methods.
var addresses = message.getTo() + ',' + message.getCc();
// Filter the address list to those containing the text the user
// has already entered.
var suggestionList = [];
addresses.split(',').forEach(function(email) {
if (email.toLowerCase().indexOf(userInput) !== -1) {
suggestionList.push(email);
}
});
suggestionList.sort();
return CardService.newSuggestionsResponseBuilder()
.setSuggestions(CardService.newSuggestions()
.addSuggestions(suggestionList))
.build(); // Don't forget to build the response!
}
คำแนะนำและ OnChangeAction()
วิดเจ็ตอินพุตข้อความอาจกำหนดฟังก์ชันแฮนเดิล setOnChangeAction()
ให้ทำงานเมื่อวิดเจ็ตขาดโฟกัส
หากตัวแฮนเดิลและคำแนะนำนี้เปิดใช้งานไว้สำหรับการป้อนข้อความเดียวกัน กฎต่อไปนี้จะกำหนดลักษณะการทำงานของการโต้ตอบในการป้อนข้อความ
- ตัวแฮนเดิล
setOnChangeAction()
จะทำงานหลังจากเลือกคำแนะนำ - หากผู้ใช้กด Enter (หรือทำให้การป้อนข้อความเสียโฟกัส) โดยไม่แก้ไขคำแนะนำที่เลือก
setOnChangeAction()
จะไม่ทริกเกอร์อีก setOnChangeAction()
จะทริกเกอร์อีกครั้งหากผู้ใช้แก้ไขคำแนะนำเพื่อไม่ให้ตรงกับคำแนะนำใดๆ ในรายการอีกต่อไป- หากผู้ใช้ไม่ได้เลือกคำแนะนำ
setOnChangeAction()
จะทริกเกอร์เมื่อการป้อนข้อความสูญเสียโฟกัส