วิดเจ็ตคือองค์ประกอบ UI ที่ให้สิ่งต่อไปนี้อย่างน้อย 1 รายการ
- โครงสร้างสำหรับวิดเจ็ตอื่นๆ เช่น การ์ดและส่วน
- ข้อมูลแก่ผู้ใช้ เช่น ข้อความและรูปภาพ หรือ
- โอกาสในการดําเนินการ เช่น ปุ่ม ช่องป้อนข้อความ หรือช่องทําเครื่องหมาย
ชุดวิดเจ็ตที่เพิ่มลงในส่วนการ์ดจะกำหนด UI ส่วนเสริมโดยรวม วิดเจ็ตจะมีลักษณะและฟังก์ชันเหมือนกันทั้งบนเว็บและอุปกรณ์เคลื่อนที่ เอกสารอ้างอิงอธิบายวิธีการต่างๆ ในการสร้างชุดวิดเจ็ต
ประเภทวิดเจ็ต
โดยทั่วไปแล้ววิดเจ็ตส่วนเสริมจะแบ่งออกเป็น 3 กลุ่ม ได้แก่ วิดเจ็ตโครงสร้าง วิดเจ็ตที่ให้ข้อมูล และวิดเจ็ตสำหรับโต้ตอบของผู้ใช้
วิดเจ็ตเชิงโครงสร้าง
วิดเจ็ตเชิงโครงสร้างมีคอนเทนเนอร์และการจัดระเบียบสำหรับวิดเจ็ตอื่นๆ ที่ใช้ใน UI
- ชุดปุ่ม ชุดปุ่มข้อความหรือรูปภาพอย่างน้อย 1 ปุ่มที่จัดกลุ่มไว้ด้วยกันในแถวแนวนอน
- การ์ด - การ์ดบริบท 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();
การ์ด Peek
เมื่อเนื้อหาตามบริบทใหม่ทริกเกอร์โดยการดำเนินการของผู้ใช้ เช่น การเปิดข้อความ Gmail คุณจะแสดงเนื้อหาบริบทใหม่ได้ทันที (ลักษณะการทำงานเริ่มต้น) หรือแสดงการแจ้งเตือนการ์ดแอบดูที่ด้านล่างของแถบด้านข้าง หากผู้ใช้คลิกกลับ เพื่อกลับไปยังหน้าแรกขณะที่ทริกเกอร์ตามบริบททำงานอยู่ การ์ด Peek จะปรากฏขึ้นเพื่อช่วยให้ผู้ใช้พบเนื้อหาตามบริบทอีกครั้ง
หากต้องการแสดงการ์ด "ดูการ์ด" เมื่อมีเนื้อหาตามบริบทใหม่พร้อมใช้งาน ให้เพิ่ม .setDisplayStyle(CardService.DisplayStyle.PEEK)
ลงในชั้นเรียน CardBuilder
แทนที่จะแสดงเนื้อหาตามบริบทใหม่ทันที การ์ดแสดงชั่วครู่จะปรากฏขึ้นเมื่อมีการส่งออบเจ็กต์ของการ์ดรายการเดียวกลับมาพร้อมกับทริกเกอร์ตามบริบทเท่านั้น มิเช่นนั้น การ์ดที่แสดงจะแทนที่การ์ดปัจจุบันทันที
หากต้องการปรับแต่งส่วนหัวของการ์ดแสดงผล ให้เพิ่มเมธอด .setPeekCardHeader()
ที่มีออบเจ็กต์ CardHeader
มาตรฐานเมื่อสร้างการ์ดบริบท โดยค่าเริ่มต้น ส่วนหัวของการ์ด Peek จะมีเฉพาะชื่อของส่วนเสริมเท่านั้น
โค้ดต่อไปนี้โดยอิงตามการเริ่มใช้งานส่วนเสริม Google Workspace อย่างรวดเร็ว ซึ่งจะแจ้งเตือนผู้ใช้เกี่ยวกับเนื้อหาตามบริบทใหม่ด้วยการ์ด Peek และปรับแต่งส่วนหัวของการ์ด Peek เพื่อแสดงหัวเรื่องของชุดข้อความ 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 - สตริงเนื้อหาข้อความที่คุณจับคู่กับองค์ประกอบอื่นๆ ได้ เช่น ป้ายกำกับข้อความด้านบนและด้านล่าง และรูปภาพหรือไอคอน วิดเจ็ต decorationedText ยังรวมวิดเจ็ต ปุ่มหรือ Switch ได้ด้วย สวิตช์ที่เพิ่มเข้ามาอาจเป็นปุ่มเปิด/ปิดหรือช่องทำเครื่องหมาย ข้อความเนื้อหาของวิดเจ็ต decorationedText ใช้การจัดรูปแบบ HTML ได้ ป้ายกำกับด้านบนและด้านล่างต้องใช้ข้อความธรรมดา
- ย่อหน้าข้อความ - ย่อหน้าข้อความ ซึ่งอาจรวมถึงองค์ประกอบที่จัดรูปแบบ HTML ได้
วิดเจ็ตการโต้ตอบของผู้ใช้
วิดเจ็ตการโต้ตอบของผู้ใช้จะช่วยให้ส่วนเสริมตอบสนองต่อการดำเนินการของผู้ใช้ได้ คุณกำหนดค่าวิดเจ็ตเหล่านี้ให้มีการตอบกลับการดำเนินการให้แสดงการ์ดต่างๆ, เปิด URL, แสดงการแจ้งเตือน, เขียนอีเมลฉบับร่าง หรือเรียกใช้ฟังก์ชัน Apps Script อื่นๆ ได้ ดูรายละเอียดในคู่มือการสร้างการ์ดแบบอินเทอร์แอกทีฟ
- การทำงานของการ์ด - รายการในเมนูที่จะอยู่ในเมนูแถบส่วนหัวของส่วนเสริม เมนูในแถบส่วนหัวอาจมีรายการที่กำหนดไว้เป็นการดำเนินการส่วนกลางซึ่งจะปรากฏในการ์ดทุกใบที่ส่วนเสริมกำหนด
- เครื่องมือเลือกวันที่ - วิดเจ็ตที่อนุญาตให้ผู้ใช้เลือกวันที่ เวลา หรือทั้งคู่ โปรดดูเครื่องมือเลือกวันที่และเวลาด้านล่างสำหรับข้อมูลเพิ่มเติม
- ปุ่มรูปภาพ - ปุ่มที่ใช้รูปภาพแทนข้อความ คุณจะใช้ไอคอนที่กำหนดล่วงหน้าแบบใดแบบหนึ่งหรือรูปภาพที่โฮสต์แบบสาธารณะที่ระบุโดย URL ก็ได้
- อินพุตการเลือก - ช่องป้อนข้อมูลที่แสดงชุดตัวเลือก วิดเจ็ตอินพุตการเลือก แสดงเป็นช่องทำเครื่องหมาย ปุ่มตัวเลือก หรือช่องสำหรับเลือกแบบเลื่อนลง
- Switch - วิดเจ็ตสลับ คุณใช้สวิตช์ร่วมกับวิดเจ็ต DecoratedText ได้เท่านั้น โดยค่าเริ่มต้น จอแสดงผลเหล่านี้จะแสดงเป็นสวิตช์เปิด/ปิด แต่คุณสามารถทำให้แสดงเป็นช่องทำเครื่องหมายแทนได้
- ปุ่มข้อความ - ปุ่มที่มีป้ายกำกับข้อความ คุณระบุการเติมสีพื้นหลังสำหรับปุ่มข้อความได้ (ค่าเริ่มต้นจะเป็นแบบโปร่งใส) คุณยังสามารถปิดใช้ปุ่มดังกล่าว ตามต้องการได้ด้วย
- การป้อนข้อความ - ช่องป้อนข้อความ วิดเจ็ตสามารถมีข้อความชื่อ ข้อความบอกใบ้ และข้อความหลายบรรทัด วิดเจ็ตจะทริกเกอร์การทำงานเมื่อค่าข้อความเปลี่ยนแปลงได้
- ตารางกริด - เลย์เอาต์หลายคอลัมน์ที่แสดงคอลเล็กชันรายการ คุณแสดงสินค้าด้วยรูปภาพ ชื่อ ชื่อรอง และตัวเลือกการปรับแต่งที่หลากหลายได้ เช่น เส้นขอบและรูปแบบการครอบตัด
DecoratedText
ช่องทำเครื่องหมาย
คุณกำหนดวิดเจ็ต DecoratedText
ที่มีช่องทำเครื่องหมายแนบอยู่ได้ แทนที่จะใช้ปุ่มหรือสวิตช์แบบไบนารี เช่นเดียวกับสวิตช์ ค่าของช่องทำเครื่องหมายจะรวมอยู่ใน
ออบเจ็กต์เหตุการณ์การกระทำ
ซึ่งส่งผ่านไปยัง 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));
เครื่องมือเลือกวันที่และเวลา
คุณสามารถกำหนดวิดเจ็ตที่อนุญาตให้ผู้ใช้เลือกเวลา วันที่ หรือทั้งคู่
คุณใช้ 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"));
ต่อไปนี้เป็นตัวอย่างของฟังก์ชันเครื่องจัดการวิดเจ็ตเครื่องมือเลือกวันที่ แฮนเดิลนี้จะจัดรูปแบบและบันทึกสตริงที่แสดงวันที่และเวลาที่ผู้ใช้เลือกในวิดเจ็ตเครื่องมือเลือกวันที่ซึ่งมีรหัส "myDateTimeChooseerWidgetID" ดังนี้
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/apps-script/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>." |
รูปแบบเวลานี้คือ |
บรรทัดใหม่ | "This is the first line. <br> This is a new line. นิ้ว |
นี่คือบรรทัดแรก นี่คือบรรทัดใหม่ |