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

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

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

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

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

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

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

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

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

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

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

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

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

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

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