Widget

Widget adalah elemen UI yang menyediakan satu atau beberapa hal berikut:

• Struktur untuk widget lain seperti kartu dan bagian,
• Informasi kepada pengguna seperti teks dan gambar, atau
• Kemampuan untuk tindakan seperti tombol, kolom input teks, atau kotak centang.

Kumpulan widget yang ditambahkan ke bagian kartu menentukan UI add-on. Widget memiliki tampilan dan fungsi yang sama di web dan perangkat seluler. Tujuan dokumentasi referensi menjelaskan beberapa metode untuk membangun set widget.

Jenis widget

Widget add-on umumnya dikategorikan menjadi tiga grup: widget struktural, widget informasi, dan widget interaksi pengguna.

Widget struktural

Widget struktural menyediakan container dan pengaturan untuk widget lainnya yang digunakan di UI.

• Kumpulan tombol—A kumpulan dari satu atau beberapa tombol teks atau gambar, yang dikelompokkan bersama dalam baris horizontal.
• Kartu—Satu konteks kartu yang berisi satu atau beberapa bagian kartu. Anda menentukan bagaimana pengguna dapat berpindah antarkartu dengan mengonfigurasi navigasi kartu.
• Header kartu—Bagian untuk kartu tertentu. Header kartu dapat memiliki judul, sub judul, dan gambar. Tindakan kartu dan tindakan universal muncul di tindakan header kartu jika add-on menggunakannya.
• Bagian kartu—A kumpulan widget yang dikumpulkan, dibagi dari bagian kartu lainnya dengan garis horizontal dan secara opsional memiliki header bagian. Setiap kartu harus memiliki setidaknya satu bagian kartu. Anda tidak dapat menambahkan kartu atau header kartu ke kartu bagian.

Selain widget struktural dasar ini, dalam Add-on Google Workspace yang dapat Anda gunakan Layanan kartu untuk membuat struktur yang tumpang-tindih dengan kartu saat ini: footer tetap dan kartu intip:

Footer tetap

Anda dapat menambahkan baris tombol tetap ke bagian bawah kartu. Baris ini tidak bergerak atau ter-scroll bersama konten kartu lainnya.

Hal berikut kutipan kode menunjukkan cara menentukan contoh footer tetap dan menambahkannya ke kartu:

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();

Kartu intip

Saat konten kontekstual baru dipicu oleh tindakan pengguna, seperti membuka pesan Gmail, Anda dapat langsung menampilkan konten kontekstual baru (perilaku default) atau tampilkan notifikasi kartu intip di bagian bawah di bilah sisi. Jika pengguna mengklik Kembali arrow_back untuk kembali ke beranda saat pemicu kontekstual aktif, kartu intip akan muncul untuk membantu pengguna menemukan konten kontekstual lagi.

Untuk menampilkan kartu intip saat konten kontekstual baru tersedia, sebagai ganti segera menampilkan konten kontekstual baru, menambahkan .setDisplayStyle(CardService.DisplayStyle.PEEK) ke CardBuilder . Kartu intip hanya muncul jika satu objek kartu dikembalikan dengan pemicu kontekstual; jika tidak, kartu yang dikembalikan akan langsung menggantikan kartu saat ini.

Untuk menyesuaikan header kartu intip, tambahkan metode .setPeekCardHeader() dengan CardHeader standar saat membuat kartu kontekstual. Secara default, header Kartu intip hanya berisi nama add-on Anda.

Kode berikut, berdasarkan pada Panduan memulai Add-on Google Workspace Cats, memberi tahu pengguna tentang konten kontekstual baru dengan Kartu intip dan melakukan penyesuaian header kartu Intip untuk menampilkan pesan Gmail yang dipilih subjek utas.

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);

Widget informasi

Widget informasi menyajikan informasi kepada pengguna.

• Gambar—Gambar ditunjukkan oleh URL yang dihosting dan dapat diakses secara publik yang Anda berikan.
• DecoratedText—A teks string konten yang dapat dipasangkan dengan elemen lain seperti bagian atas dan bawah label teks, dan gambar atau ikon. Widget DecoratedText juga dapat menyertakan Tombol atau Widget Tombol. Tombol akses ditambahkan dapat berupa tombol beralih atau kotak centang. Teks konten dari widget DecoratedText dapat menggunakan Pemformatan HTML; terpopuler dan label bawah harus menggunakan teks polos.
• Paragraf teks—A paragraf teks, yang dapat mencakup Elemen berformat HTML.

Widget interaksi pengguna

Widget interaksi pengguna memungkinkan add-on merespons tindakan yang diambil oleh pelanggan. Anda dapat mengonfigurasi widget ini dengan respons tindakan untuk menampilkan kartu yang berbeda, membuka URL, menampilkan notifikasi, menulis draf email, atau menjalankan fungsi Apps Script lainnya. Lihat Panduan Membuat Kartu Interaktif untuk spesifikasi pendukung.

• Tindakan kartu—Menu yang ditempatkan di menu panel header add-on. Menu bilah {i>header<i} juga dapat berisi item yang didefinisikan sebagai tindakan universal, yang muncul di setiap kartu yang ditentukan oleh add-on.
• Alat pilih DateTime—widget yang memungkinkan pengguna memilih tanggal, waktu, atau keduanya. Lihat Alat pilih tanggal dan waktu di bawah untuk informasi lebih lanjut.
• Tombol gambar—A tombol yang menggunakan gambar, bukan teks. Anda dapat menggunakan salah satu dari beberapa ikon standar atau gambar yang dihosting secara publik yang ditunjukkan oleh URL-nya.
• Input pilihan— input yang mewakili kumpulan opsi. Widget input pilihan tampil sebagai kotak centang, tombol pilihan, atau kotak pilihan {i>drop-down<i}.
• Tombol—Tombol . Anda hanya dapat menggunakan {i>switch<i} bersama dengan sebuah DecoratedText. Secara default ini ditampilkan sebagai tombol alih, namun Anda dapat membuatnya ditampilkan sebagai kotak centang.
• Tombol teks—A dengan label teks. Anda dapat menentukan isian warna latar belakang untuk teks (defaultnya adalah transparan). Anda juga dapat menonaktifkan tombol diperlukan.
• Input teks—Teks bidang input. Widget dapat memiliki teks judul, teks petunjuk, dan teks multibaris. Widget dapat memicu tindakan ketika nilai teks berubah.
• Petak—Multi-kolom yang mewakili sekumpulan item. Anda dapat mewakili item dengan gambar, judul, subjudul, dan berbagai opsi penyesuaian seperti batas dan gaya pemangkasan.

DecoratedText kotak centang

Anda dapat menentukan DecoratedText widget yang memiliki kotak centang terlampir, bukan tombol atau tombol alih biner {i>switch<i}. Seperti halnya {i>switch<i}, nilai dari kotak centang disertakan dalam objek peristiwa tindakan yang diteruskan ke Action dilampirkan pada DecoratedText ini dengan setOnClickAction(action) .

Cuplikan kode berikut menunjukkan cara menentukan kotak centang DecoratedText , yang kemudian dapat Anda tambahkan ke kartu:

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

Pemilih tanggal dan waktu

Anda dapat menentukan widget yang memungkinkan pengguna memilih waktu, tanggal, atau keduanya. Anda dapat menggunakan setOnChangeAction() untuk menetapkan fungsi pengendali widget ke mengeksekusi saat nilai pemilih berubah.

Cuplikan kode berikut menunjukkan cara menentukan pemilih khusus tanggal, metode Pemilih ini, dan pemilih tanggal-waktu, yang kemudian dapat Anda tambahkan ke kartu:

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"));

Berikut adalah contoh fungsi pengendali widget pemilih tanggal. Ini memformat pengendali dan mencatat string ke dalam log yang mewakili tanggal-waktu yang dipilih oleh pengguna dalam widget pemilih tanggal-waktu dengan ID "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);
  }
}

Tabel berikut menampilkan contoh UI pemilihan pemilih di desktop dan perangkat seluler perangkat. Jika dipilih, pemilih tanggal akan membuka UI kalender berbasis bulan untuk memungkinkan pengguna untuk memilih tanggal baru dengan cepat.

Saat pengguna memilih pemilih waktu di perangkat desktop, menu drop-down akan terbuka dengan daftar waktu yang dipisahkan dalam kelipatan 30 menit yang dapat dipilih pengguna dari mereka. Pengguna juga dapat mengetikkan waktu tertentu. Pada perangkat seluler yang memilih alat pilih waktu membuka "jam" seluler bawaan pemilih waktu.

Desktop	Seluler

Petak

Tampilkan item dalam tata letak multi-kolom dengan widget petak. Setiap item dapat menampilkan gambar, judul, dan subtitel. Gunakan opsi konfigurasi tambahan untuk atur posisi teks relatif terhadap gambar dalam item petak.

Anda dapat mengonfigurasi item petak dengan ID yang ditampilkan sebagai parameter ke tindakan yang ditentukan pada 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"));

Pemformatan teks

Beberapa widget berbasis teks dapat mendukung pemformatan HTML teks sederhana. Saat menetapkan konten teks dari widget ini, cukup sertakan tag HTML yang sesuai.

Tag yang didukung dan tujuannya ditampilkan dalam tabel: