วิดเจ็ต

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

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

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

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

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

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

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

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

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

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

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

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

ช่องทำเครื่องหมาย 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"));

ต่อไปนี้คือตัวอย่างของฟังก์ชันเครื่องจัดการวิดเจ็ตเครื่องมือเลือกวันที่ ช่วงเวลานี้ รูปแบบตัวแฮนเดิลและบันทึกสตริงที่แสดงวันที่และเวลาที่เลือกโดย ผู้ใช้ในวิดเจ็ตเครื่องมือเลือกวันที่และเวลาที่มีรหัส "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/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 ที่เกี่ยวข้องไว้ด้วย

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