วิดเจ็ต

วิดเจ็ตคือองค์ประกอบ UI ที่มีฟีเจอร์ต่อไปนี้อย่างน้อย 1 รายการ

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

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

ประเภทวิดเจ็ต

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

วิดเจ็ตโครงสร้าง

วิดเจ็ตโครงสร้างมีคอนเทนเนอร์และจัดระเบียบวิดเจ็ตอื่นๆ ที่ใช้ใน UI

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

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

นอกจากวิดเจ็ตโครงสร้างพื้นฐานเหล่านี้แล้ว คุณยังใช้ บริการการ์ดเพื่อสร้างโครงสร้างที่ซ้อนทับการ์ดปัจจุบันได้ในส่วนเสริมของ Google Workspace ได้แก่ ส่วนท้ายแบบคงที่ และ การ์ดแบบย่อ:

ส่วนท้ายแบบคงที่

คุณสามารถเพิ่มแถวของปุ่มแบบคงที่ที่ด้านล่างของการ์ดได้ แถวนี้จะไม่เลื่อนหรือเลื่อนไปพร้อมกับเนื้อหาอื่นๆ ของการ์ด

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีกำหนดส่วนท้ายแบบคงที่และเพิ่มลงในการ์ด

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("Primary")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("Secondary")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "secondaryCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

การ์ดแบบย่อ

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

หากต้องการแสดงการ์ดแบบย่อเมื่อมีเนื้อหาตามบริบทใหม่ ให้เพิ่ม .setDisplayStyle(CardService.DisplayStyle.PEEK) ลงใน CardBuilder คลาส การ์ดแบบย่อจะปรากฏขึ้นก็ต่อเมื่อระบบส่งคืนออบเจ็กต์การ์ดเดียวพร้อมทริกเกอร์ตามบริบท ไม่เช่นนั้น การ์ดที่ส่งคืนจะแทนที่การ์ดปัจจุบัน

หากต้องการปรับแต่งส่วนหัวของการ์ดแบบย่อ ให้เพิ่มเมธอด .setPeekCardHeader พร้อม ออบเจ็กต์ CardHeader มาตรฐานเมื่อสร้างการ์ดตามบริบท โดยค่าเริ่มต้น ส่วนหัวของการ์ดแบบย่อ จะมีเพียงชื่อส่วนเสริมของคุณ

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

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);

วิดเจ็ตข้อมูล

วิดเจ็ตข้อมูลจะแสดงข้อมูลต่อผู้ใช้

• รูปภาพ: รูปภาพที่ระบุ ด้วย URL ที่โฮสต์และเข้าถึงได้แบบสาธารณะ
• DecoratedText: สตริงเนื้อหาข้อความที่คุณจับคู่กับองค์ประกอบอื่นๆ ได้ เช่น ป้ายกำกับด้านบนและ ด้านล่าง รวมถึงรูปภาพหรือไอคอน วิดเจ็ต DecoratedText ยังมีวิดเจ็ต ปุ่มหรือ สวิตช์ได้ด้วย สวิตช์ที่เพิ่ม อาจเป็นสวิตช์เปิด/ปิดหรือช่องทำเครื่องหมาย ข้อความเนื้อหา ใช้การจัดรูปแบบ HTMLได้ แต่ป้ายกำกับด้านบนและด้านล่าง ต้องใช้ข้อความธรรมดา
• ย่อหน้าข้อความ: ย่อหน้าข้อความซึ่งอาจมีองค์ประกอบที่จัดรูปแบบ HTML

วิดเจ็ตการโต้ตอบของผู้ใช้

วิดเจ็ตการโต้ตอบของผู้ใช้ช่วยให้ส่วนเสริมตอบสนองต่อการดำเนินการของผู้ใช้ได้ กำหนดค่าวิดเจ็ตเหล่านี้ด้วยการตอบสนองต่อการดำเนินการเพื่อแสดงการ์ดต่างๆ เปิด URL แสดงการแจ้งเตือน สร้างอีเมลฉบับร่าง หรือเรียกใช้ฟังก์ชันอื่นๆ ของ Apps Script ดูรายละเอียดได้ที่ คู่มือการสร้างการ์ดแบบอินเทอร์แอกทีฟ

• การดำเนินการของการ์ด: รายการเมนู ที่วางไว้ในเมนูแถบส่วนหัวของส่วนเสริม เมนู แถบส่วนหัวยังอาจมีรายการที่กำหนดเป็นการดำเนินการสากล ซึ่งจะปรากฏในการ์ดทุกใบ ที่ส่วนเสริมกำหนด
• เครื่องมือเลือกวันที่และเวลา: วิดเจ็ตที่ช่วยให้ผู้ใช้ เลือกวันที่ เวลา หรือทั้งวันที่และเวลาได้ ดูข้อมูลเพิ่มเติมได้ที่ เครื่องมือเลือกวันที่และเวลา
• ปุ่มรูปภาพ: ปุ่มที่ใช้รูปภาพแทนข้อความ ใช้ไอคอนที่กำหนดไว้ล่วงหน้าหลายรายการหรือรูปภาพที่โฮสต์แบบสาธารณะ
• อินพุตการเลือก: ช่องป้อนข้อมูลที่แสดงถึงคอลเล็กชันตัวเลือก วิดเจ็ตอินพุตการเลือกจะแสดงเป็นช่องทำเครื่องหมาย ปุ่มตัวเลือก หรือกล่องการเลือกแบบเลื่อนลง
• สวิตช์: วิดเจ็ตสวิตช์เปิด/ปิดที่ใช้กับวิดเจ็ต DecoratedText โดยค่าเริ่มต้น วิดเจ็ตเหล่านี้จะแสดงเป็นสวิตช์เปิด/ปิด แต่คุณสามารถแสดงเป็น ช่องทำเครื่องหมายได้
• ปุ่มข้อความ: ปุ่มที่มีป้ายกำกับข้อความ ระบุการเติมสีพื้นหลังสำหรับปุ่มข้อความ (ค่าเริ่มต้นคือโปร่งใส) นอกจากนี้ คุณยังปิดใช้ปุ่มได้ตามต้องการ
• **อินพุตข้อความ**: ช่องป้อนข้อความ วิดเจ็ตอาจมีข้อความชื่อ ข้อความคำแนะนำ และข้อความหลายบรรทัด วิดเจ็ตสามารถทริกเกอร์การดำเนินการเมื่อค่าข้อความเปลี่ยนแปลง
• ตารางกริด: เลย์เอาต์หลายคอลัมน์ แสดงรายการด้วยรูปภาพ ชื่อ คำบรรยาย และตัวเลือกการปรับแต่ง เช่น เส้นขอบและสไตล์การครอบตัด

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

คุณสามารถกำหนดDecoratedText วิดเจ็ตที่มีช่องทำเครื่องหมายแนบอยู่แทนปุ่มหรือสวิตช์เปิด/ปิดแบบไบนารี ค่าของช่องทำเครื่องหมายจะรวมอยู่ใน ออบเจ็กต์เหตุการณ์การดำเนินการ ที่ส่งไปยัง Action ที่แนบ กับ DecoratedText นี้ด้วยเมธอด setOnClickAction เช่นเดียวกับสวิตช์เปิด/ปิด

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีกำหนดวิดเจ็ต DecoratedText ที่มีช่องทำเครื่องหมายเพื่อเพิ่มลงในการ์ด

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

เครื่องมือเลือกวันที่และเวลา

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

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีกำหนดเครื่องมือเลือกวันที่เท่านั้น เครื่องมือเลือกเวลาเท่านั้น และเครื่องมือเลือกวันที่และเวลาเพื่อเพิ่มลงในการ์ด

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter a date")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter a time")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter a date and time")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));

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

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See:
  // https://developers.google.com/workspace/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

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

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

เดสก์ท็อป	มือถือ

ตารางกริด

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

กำหนดค่ารายการตารางกริดด้วยตัวระบุที่จะส่งคืนเป็นพารามิเตอร์ไปยังการดำเนินการที่กำหนดไว้ในตารางกริด

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.RECTANGLE_4_3);

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

var grid = CardService.newGrid()
  .setTitle("Recently viewed")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));

การจัดรูปแบบข้อความ

วิดเจ็ตบางรายการที่อิงตามข้อความรองรับการจัดรูปแบบ HTML ข้อความพื้นฐาน เมื่อตั้งค่าเนื้อหาข้อความของวิดเจ็ตเหล่านี้ ให้ใส่แท็ก HTML ที่เกี่ยวข้อง

แท็กที่รองรับและวัตถุประสงค์ของแท็กจะแสดงในตารางต่อไปนี้