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

วิดเจ็ต

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

วิดเจ็ตที่ให้ข้อมูล

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

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

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

ตัวอย่างวิดเจ็ตช่องทำเครื่องหมายที่มีการตกแต่งข้อความ

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

คุณสามารถกำหนดวิดเจ็ตที่อนุญาตให้ผู้ใช้เลือกเวลา วันที่ หรือทั้ง 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"));

ต่อไปนี้เป็นตัวอย่างของฟังก์ชันเครื่องจัดการวิดเจ็ตเครื่องมือเลือกวันที่ แฮนเดิลนี้จะจัดรูปแบบและบันทึกสตริงที่แสดงวันที่และเวลาที่ผู้ใช้เลือกในวิดเจ็ตเครื่องมือเลือกวันที่ซึ่งใช้รหัส "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>."`	รูปแบบเวลานี้คือ 16-02-2023 15:00
บรรทัดใหม่	`"This is the first line. <br> This is a new line.` นิ้ว	นี่คือบรรทัดแรก นี่คือบรรทัดใหม่

วิดเจ็ต

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

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

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

การ์ด Peek

วิดเจ็ตที่ให้ข้อมูล

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

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

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

GRid

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

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