ออกแบบการ์ดหรือกล่องโต้ตอบแบบอินเทอร์แอกทีฟ

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

ออกแบบและแสดงตัวอย่างการ์ดด้วยเครื่องมือสร้างการ์ด

เปิดเครื่องมือสร้างการ์ด

ข้อกำหนดเบื้องต้น

  • บัญชี Google Workspace ที่มีสิทธิ์เข้าถึง Google Chat
  • แอป Chat ที่เผยแพร่แล้ว หากต้องการสร้าง แอป Chat ให้ทำตาม quickstartนี้

    • เพิ่มปุ่ม

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

    • เปิดไฮเปอร์ลิงก์ด้วย OpenLink เพื่อให้ข้อมูลเพิ่มเติมแก่ผู้ใช้
    • เรียกใช้ action ที่เรียกใช้ฟังก์ชันที่กำหนดเอง เช่น การเรียก API

    ปุ่มจะรองรับข้อความแสดงแทนสำหรับการเข้าถึงที่ง่ายขึ้น

    เพิ่มปุ่มที่เรียกใช้ฟังก์ชันที่กำหนดเอง

    ต่อไปนี้เป็นการ์ดที่ประกอบด้วยวิดเจ็ต ButtonList ที่มี 2 ปุ่ม ปุ่มเดียวจะเปิดเอกสารประกอบสําหรับนักพัฒนาซอฟต์แวร์ Google Chat ในแท็บใหม่ ปุ่มอื่นๆ จะเรียกใช้ฟังก์ชันที่กำหนดเองชื่อ goToView() และส่งผ่านพารามิเตอร์ viewType="BIRD EYE VIEW"

    เพิ่มปุ่มที่มีสีที่กำหนดเองและปุ่มที่ปิดใช้งาน

    คุณป้องกันไม่ให้ผู้ใช้คลิกปุ่มได้โดยการตั้งค่า "disabled": "true"

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

    เพิ่มปุ่มที่มีไอคอน

    การ์ดต่อไปนี้จะแสดงการ์ดที่ประกอบด้วยวิดเจ็ต ButtonList พร้อมวิดเจ็ต 2 ไอคอน Button ปุ่มเดียวใช้ช่อง knownIcon เพื่อแสดงไอคอนอีเมลในตัวของ Google Chat ปุ่มอีกปุ่มหนึ่งใช้ช่อง iconUrl เพื่อแสดงวิดเจ็ตไอคอนที่กำหนดเอง

    เพิ่มปุ่มที่มีไอคอนและข้อความ

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

    เพิ่มองค์ประกอบ UI ที่เลือกได้

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

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

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

    ส่วนนี้จะแสดงตัวอย่างของการ์ดที่ใช้วิดเจ็ต SelectionInput ตัวอย่างใช้อินพุตส่วนประเภทต่างๆ ดังนี้

    เพิ่มช่องทำเครื่องหมาย

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

    เพิ่มปุ่มตัวเลือก

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

    เพิ่มสวิตช์

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

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

    เพิ่มเมนูแบบเลือกหลายรายการ

    หน้าต่างต่อไปนี้จะแสดงกล่องโต้ตอบที่ขอให้ผู้ใช้เลือกรายชื่อติดต่อจากเมนูเลือกหลายรายการ

    ใช้แหล่งข้อมูลสำหรับเมนูแบบเลือกหลายรายการ

    ส่วนต่อไปนี้จะอธิบายวิธีใช้เมนูแบบเลือกหลายรายการเพื่อป้อนข้อมูลจากแหล่งที่มาแบบไดนามิก เช่น แอปพลิเคชัน Google Workspace หรือแหล่งข้อมูลภายนอก

    แหล่งข้อมูลจาก Google Workspace

    คุณจะป้อนข้อมูลสำหรับเมนูแบบเลือกหลายรายการได้จากแหล่งข้อมูลต่อไปนี้ใน Google Workspace

    • ผู้ใช้ Google Workspace: คุณจะเพิ่มผู้ใช้ภายในองค์กร Google Workspace เดียวกันได้เท่านั้น
    • พื้นที่ใน Chat: ผู้ใช้ที่ป้อนข้อมูลในเมนูแบบเลือกหลายรายการจะดูและเลือกพื้นที่ทำงานที่ตนอยู่ในองค์กร Google Workspace ได้เท่านั้น

    หากต้องการใช้แหล่งข้อมูลของ Google Workspace ให้ระบุช่อง platformDataSource คุณจะละเว้นออบเจ็กต์ SectionItem ได้ ซึ่งต่างจากอินพุตการเลือกประเภทอื่นๆ เนื่องจากรายการการเลือกเหล่านี้จะมาจาก Google Workspace แบบไดนามิก

    รหัสต่อไปนี้แสดงเมนูแบบเลือกหลายรายการของผู้ใช้ Google Workspace หากต้องการเติมข้อมูลผู้ใช้ อินพุตการเลือกจะตั้งค่า commonDataSource เป็น USER ดังนี้

    JSON

    {
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

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

    JSON

    {
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}
    แหล่งข้อมูลภายนอก Google Workspace

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

    หากต้องการใช้แหล่งข้อมูลภายนอก ให้ใช้ช่อง externalDataSource เพื่อระบุฟังก์ชันที่แสดงรายการจากแหล่งข้อมูล

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

    รหัสต่อไปนี้จะแสดงเมนูแบบเลือกหลายรายการจากชุดรายชื่อติดต่อภายนอกสำหรับผู้ใช้ เมนูจะแสดงรายชื่อติดต่อ 1 รายการโดยค่าเริ่มต้น และเรียกใช้ฟังก์ชัน getContacts เพื่อเรียกและป้อนข้อมูลรายการจากแหล่งข้อมูลภายนอก

    JSON

    {
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

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

    หากต้องการเติมข้อความอัตโนมัติในรายการ ให้สร้างฟังก์ชันที่ค้นหาแหล่งข้อมูลภายนอกและแสดงรายการเมื่อผู้ใช้พิมพ์ในเมนูแบบเลือกหลายรายการ ฟังก์ชันการทำงานนี้ต้องมีลักษณะดังนี้

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

    โค้ดต่อไปนี้จะเติมข้อความอัตโนมัติจากรายการจากแหล่งข้อมูลภายนอก จากตัวอย่างข้างต้น แอป Chat จะแนะนำรายการต่างๆ โดยอิงตามเวลาที่ฟังก์ชัน getContacts ทริกเกอร์ ดังนี้

    Apps Script

    apps-script/selection-input/on-widget-update.gs
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Node.js

    node/selection-input/on-widget-update.js
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    เพิ่มฟิลด์ที่ผู้ใช้สามารถป้อนข้อความ

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

    หากต้องการรวบรวมข้อมูลที่เป็นนามธรรมหรือไม่ทราบจากผู้ใช้ ให้ใช้วิดเจ็ต TextInput นี้ หากต้องการรวบรวมข้อมูลที่กำหนดไว้จากผู้ใช้ ให้ใช้วิดเจ็ต SelectionInput แทน

    หากต้องการประมวลผลข้อความที่ผู้ใช้ป้อน โปรดดูรับข้อมูลแบบฟอร์ม

    ต่อไปนี้เป็นการ์ดที่ประกอบด้วยวิดเจ็ต TextInput

    ให้ผู้ใช้เลือกวันที่และเวลา

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

    หากต้องการประมวลผลค่าวันที่และเวลาที่ผู้ใช้ป้อน โปรดดูหัวข้อรับข้อมูลแบบฟอร์ม

    การ์ดต่อไปนี้จะแสดงการ์ดที่ประกอบด้วยวิดเจ็ต DateTimePicker 3 ประเภท

    แก้ปัญหา

    เมื่อแอป Google Chat หรือการ์ดแสดงผลข้อผิดพลาด อินเทอร์เฟซ Chat จะแสดงข้อความว่า "เกิดข้อผิดพลาด" หรือ "ดำเนินการตามคำขอของคุณไม่ได้" บางครั้ง UI ของ Chat ไม่แสดงข้อความแสดงข้อผิดพลาด แต่แอปหรือการ์ด Chat จะให้ผลลัพธ์ที่ไม่คาดคิด เช่น ข้อความการ์ดอาจไม่ปรากฏ

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