วิดเจ็ต

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

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

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

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

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

หมายเหตุ: การ์ดตัวอย่างเพลงจะไม่ปรากฏในแอปบนอุปกรณ์เคลื่อนที่

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

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 ยังรวมวิดเจ็ต Button หรือ Switch ได้ด้วย สวิตช์ที่เพิ่มเข้ามาอาจเป็นปุ่มเปิด/ปิดหรือช่องทำเครื่องหมาย ข้อความเนื้อหาของวิดเจ็ต DecoratedText สามารถใช้การจัดรูปแบบ HTML ส่วนป้ายกำกับด้านบนและด้านล่างต้องใช้ข้อความธรรมดา
• ย่อหน้าข้อความ - ย่อหน้าข้อความที่อาจมีองค์ประกอบรูปแบบ HTML

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

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

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

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

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

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

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

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

คุณสามารถกําหนดวิดเจ็ตที่อนุญาตให้ผู้ใช้เลือกเวลา วันที่ หรือทั้ง 2 อย่าง คุณสามารถใช้ 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 นาทีซึ่งผู้ใช้สามารถเลือกได้ ผู้ใช้ยังพิมพ์เวลาที่ต้องการได้ด้วย ในอุปกรณ์เคลื่อนที่ การเลือกเครื่องมือเลือกเวลาจะเปิดเครื่องมือเลือกเวลา "นาฬิกา" ในตัวของอุปกรณ์เคลื่อนที่

เดสก์ท็อป	อุปกรณ์เคลื่อนที่

GRid

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

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

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 ที่เกี่ยวข้อง

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

รูปแบบ	ตัวอย่าง	ผลลัพธ์ที่ผ่านการจัดการแสดงผล
ตัวหนา	"This is <b>bold</b>."	ข้อความนี้เป็นตัวหนา
ตัวเอียง	"This is <i>italics</i>."	ข้อความนี้เป็นตัวเอียง
ขีดเส้นใต้	"This is <u>underline</u>."	นี่เป็นขีดเส้นใต้
ขีดทับ	"This is <s>strikethrough</s>."	ข้อความนี้มีขีดทับ
สีแบบอักษร	"This is <font color=\"#FF0000\">red font</font>."	นี่คือแบบอักษรสีแดง
ไฮเปอร์ลิงก์	"This is a <a href=\"https://www.google.com\">hyperlink</a>."	นี่เป็นไฮเปอร์ลิงก์
เวลา	"This is a time format: <time>2023-02-16 15:00</time>."	รูปแบบเวลาคือ 2023-02-16 15:00
ขึ้นบรรทัดใหม่	"This is the first line. <br> This is a new line."	นี่คือบรรทัดแรก บรรทัดใหม่