คำแนะนำที่เติมข้อความอัตโนมัติสำหรับการป้อนข้อความ

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

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

การกำหนดค่าคำแนะนำ

การกำหนดค่าคำแนะนำสำหรับการป้อนข้อความกำหนดให้คุณต้องดำเนินการต่อไปนี้เท่านั้น

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

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

คำแนะนำแบบคงที่

หากต้องการเสนอคำแนะนำแบบคงที่ ให้ทำตามขั้นตอนต่อไปนี้

1. สร้างออบเจ็กต์ Suggestions
2. เพิ่มคำแนะนำแบบคงที่แต่ละรายการลงในคำแนะนำโดยใช้ addSuggestion() หรือ addSuggestions()
3. แนบออบเจ็กต์ Suggestions กับวิดเจ็ตโดยใช้ TextInput.setSuggestions()

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

การดำเนินการที่แนะนำ

หากคุณไม่ได้ใช้รายการคำแนะนำแบบคงที่ คุณต้องกำหนดการดำเนินการเพื่อสร้างคำแนะนำแบบไดนามิก โดยทำตามขั้นตอนต่อไปนี้

1. สร้างออบเจ็กต์ Action และเชื่อมโยงออบเจ็กต์กับฟังก์ชันเรียกกลับที่คุณกำหนด
2. เรียกใช้ฟังก์ชัน TextInput.setSuggestionsAction() ของวิดเจ็ต โดยใส่ออบเจ็กต์ Action
3. ให้ใช้ฟังก์ชันเรียกกลับเพื่อสร้างรายการคำแนะนำและแสดงผลออบเจ็กต์ SuggestionsResponse ที่สร้างขึ้น

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

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

ตัวอย่าง

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

// 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() ไว้ ซึ่งจะทำงานทุกครั้งที่วิดเจ็ตสูญเสียโฟกัส หากเปิดใช้ทั้งเครื่องจัดการและคำแนะนำนี้สำหรับการป้อนข้อความเดียวกัน กฎต่อไปนี้จะกำหนดลักษณะการโต้ตอบของอินพุตข้อความ

1. ตัวแฮนเดิล setOnChangeAction() จะทำงานหลังจากเลือกคำแนะนำ
2. หากผู้ใช้กด Enter (หรือทำให้การป้อนข้อความหลุดโฟกัส) โดยไม่แก้ไขคำแนะนำที่เลือก setOnChangeAction() จะไม่ทริกเกอร์อีก
3. setOnChangeAction() จะทริกเกอร์อีกครั้งหากผู้ใช้เลือกคำแนะนำแล้ว การแก้ไขดังกล่าวจะไม่ตรงกับคำแนะนำในรายการอีกต่อไป
4. หากผู้ใช้ไม่ได้เลือกคำแนะนำ setOnChangeAction() จะทำงานเมื่อการป้อนข้อความหลุดโฟกัส