หน้านี้ได้รับการแปลโดย Cloud Translation API

วิดเจ็ต

วิดเจ็ตเป็นองค์ประกอบ UI แบบง่ายที่ให้ข้อมูลต่อไปนี้อย่างน้อย 1 อย่าง

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

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

ใช้ชุดออกแบบส่วนเสริมของ Google Workspace

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

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

ดาวน์โหลดชุดเครื่องมือออกแบบ

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

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

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

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

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

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

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

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

ส่วนท้ายที่แก้ไขแล้ว

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

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

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

แสดงการ์ด

ตัวอย่างการ์ดตัวอย่าง

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

หากต้องการแสดงการ์ดตัวอย่างเมื่อมีการแสดงเนื้อหาบริบทใหม่ ให้เพิ่ม .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 - สตริงเนื้อหาข้อความที่คุณสามารถจับคู่กับองค์ประกอบอื่นๆ เช่น ป้ายกํากับข้อความด้านบนและด้านล่าง และรูปภาพหรือไอคอน วิดเจ็ต DecoratedText ยังอาจมีวิดเจ็ตปุ่มหรือสวิตช์ได้เช่นกัน สวิตช์ที่เพิ่มจะเป็นตัวสลับแบบง่ายหรือช่องทําเครื่องหมาย ข้อความเนื้อหาของวิดเจ็ต decorationedText สามารถใช้การจัดรูปแบบ HTML ป้ายบนสุดและล่างสุดจะต้องใช้ข้อความธรรมดา
ข้อความย่อหน้า - ย่อหน้าข้อความอย่างง่าย ซึ่งอาจรวมถึงรูปแบบ HTML

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

วิดเจ็ตการทํางานของการ์ด

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

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

การดําเนินการของการ์ด - รายการในเมนูที่วางอยู่ในเมนูส่วนหัวของส่วนเสริม เมนูแถบส่วนหัวยังสามารถเก็บรายการที่กําหนดไว้เป็นการดําเนินการสากล ซึ่งจะปรากฏในการ์ดทุกใบที่ส่วนเสริมกําหนดไว้
เครื่องมือเลือกวันที่และเวลา วิดเจ็ตที่อนุญาตให้ผู้ใช้เลือกวันที่ เวลา หรือทั้งสองอย่าง ดูเครื่องมือเลือกวันที่และเวลาด้านล่างเพื่อดูข้อมูลเพิ่มเติม
ปุ่มรูปภาพ - ปุ่มที่ใช้รูปภาพแทนข้อความ คุณสามารถใช้ไอคอนที่กําหนดไว้ล่วงหน้า หรือรูปภาพที่โฮสต์แบบสาธารณะซึ่งระบุโดย URL
อินพุตการเลือก - ช่องอินพุตที่แสดงคอลเล็กชันตัวเลือก วิดเจ็ตอินพุตการเลือกเป็นช่องทําเครื่องหมาย ปุ่มตัวเลือก หรือช่องสําหรับเลือกแบบเลื่อนลง
Switch — วิดเจ็ตสลับ คุณใช้สวิตช์ร่วมกับวิดเจ็ต 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 the 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 the 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 the date and time in EDT 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"));

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

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("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

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

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .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</text>."`	นี่คือแบบอักษรสีแดง
ไฮเปอร์ลิงก์	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	นี่คือไฮเปอร์ลิงก์
เวลา	`"This is a time format: <time>2023-02-16 15:00</time>."`	รูปแบบเวลาคือ 2023-05-10 15:00
บรรทัดใหม่	`"This is the first line. <br> This is a new line.` นิ้ว	นี่คือบรรทัดแรก นี่คือบรรทัดใหม่