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

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

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

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

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

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

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

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

หากต้องการแสดงรายการคำแนะนำแบบคงที่ คุณต้องทำดังนี้

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

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

การดำเนินการตามคำแนะนำ

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

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

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

ฟังก์ชัน Callback ต้องแสดงผลออบเจ็กต์ 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() จะทริกเกอร์เมื่ออินพุตข้อความเสียโฟกัส