Halaman ini diterjemahkan oleh Cloud Translation API.

Widget

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

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

Kumpulan widget yang ditambahkan ke bagian kartu menentukan UI add-on secara keseluruhan. Widget memiliki tampilan dan fungsi yang sama di web dan perangkat seluler. Dokumentasi referensi menjelaskan beberapa metode untuk mem-build kumpulan widget.

Menggunakan kit desain Add-on Google Workspace

Untuk menghemat waktu mendesain widget add-on, desainer dapat menggunakan Kit desain UI add-on Google Workspace yang tersedia di Figma. Anda dapat membuat akun Figma, atau meminta lisensi dari administrator organisasi.

Jelajahi komponen dan gunakan template bawaan untuk membuat dan memvisualisasikan widget.

Dapatkan kit desain

Jenis widget

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

Widget struktural

Widget struktural menyediakan container dan pengaturan untuk widget lain yang digunakan dalam AI.

Widget struktural

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

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

Footer diperbaiki

Sekarang Anda dapat menambahkan baris tombol tetap ke bagian bawah kartu Anda. Baris ini tidak bergerak atau men-scroll dengan konten kartu lainnya. Kutipan kode berikut menunjukkan cara menentukan contoh footer tetap dan menambahkannya ke kartu:

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

Lihat kartu

Contoh kartu intip

Saat konten kontekstual baru dipicu oleh tindakan pengguna, seperti membuka pesan Gmail, Anda dapat langsung menampilkan konten kontekstual baru (perilaku default) atau menampilkan notifikasi kartu mengintip di bagian bawah sidebar. Jika pengguna mengklik Kembali untuk kembali ke halaman 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, jangan segera menampilkan konten kontekstual baru, tambahkan .setDisplayStyle(CardService.DisplayStyle.PEEK) ke class CardBuilder Anda. Kartu intip hanya muncul jika objek kartu tunggal ditampilkan dengan pemicu kontekstual; jika tidak, kartu yang dikembalikan akan langsung menggantikan kartu saat ini.

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

Kode berikut, berdasarkan Panduan memulai add-on Cats Google Workspace, memberi tahu pengguna tentang konten kontekstual baru dengan kartu Peek dan menyesuaikan header kartu Peek untuk menampilkan subjek rangkaian pesan Gmail yang dipilih.

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 yang ditunjukkan oleh URL yang dihosting dan dapat diakses secara publik yang Anda berikan.
LengkapidText—String konten teks yang dapat Anda sambungkan dengan elemen lain seperti label teks atas dan bawah, dan gambar atau ikon. Widget decorationdText juga dapat menyertakan widget Button atau Switch. Tombol yang ditambahkan dapat berupa tombol atau kotak centang sederhana. Teks konten widget LengkapidText dapat menggunakan pemformatan HTML; label atas dan bawah harus menggunakan teks biasa.
Paragraf teks—Paragraf teks sederhana, yang dapat menyertakan elemen berformat HTML.

Widget interaksi pengguna

Widget tindakan kartu

Dengan widget interaksi pengguna, add-on dapat merespons tindakan yang dilakukan oleh pengguna. Anda dapat mengonfigurasi widget ini dengan respons tindakan untuk menampilkan berbagai kartu, membuka URL, menampilkan notifikasi, menulis email draf, atau menjalankan fungsi Apps Script lainnya. Lihat panduan Membuat Kartu Interaktif untuk mengetahui detailnya.

Widget interaksi pengguna

Tindakan kartu—Item menu yang ditempatkan di menu panel header add-on. Menu kolom header juga dapat berisi item yang ditentukan sebagai tindakan universal, yang muncul di setiap kartu yang ditentukan oleh add-on.
Alat pilih Tanggal—widget yang memungkinkan pengguna memilih tanggal, waktu, atau keduanya. Lihat Alat pilih tanggal dan waktu di bawah untuk informasi selengkapnya.
Tombol gambar—Tombol yang menggunakan gambar, bukan teks. Anda dapat menggunakan salah satu dari beberapa ikon yang telah ditentukan atau gambar yang dihosting secara publik yang ditunjukkan oleh URL-nya.
Input pilihan—Kolom input yang mewakili kumpulan opsi. Widget input pilihan ditampilkan sebagai kotak centang, tombol pilihan, atau kotak pilihan drop-down.
Tombol—Widget tombol alih. Anda hanya dapat menggunakan tombol yang berkaitan dengan widget LengkapidText. Secara default, layar ini ditampilkan sebagai tombol alih, tetapi Anda dapat membuatnya ditampilkan sebagai kotak centang.
Tombol teks—Tombol dengan label teks. Anda dapat menentukan pengisian warna latar belakang untuk tombol teks (defaultnya transparan). Anda juga dapat menonaktifkan tombol sesuai kebutuhan.
Input teks—Kolom input teks. Widget dapat memiliki teks judul, teks petunjuk, dan teks multibaris. Widget dapat memicu tindakan saat nilai teks berubah.
Grid—Tata letak multi-kolom yang mewakili kumpulan item. Anda dapat merepresentasikan item dengan gambar, judul, subtitel, dan berbagai opsi penyesuaian seperti gaya batas dan pemangkasan.

Kotak centang LengkapidText

Anda dapat menentukan widget DecoratedText yang memiliki kotak centang terlampir, bukan tombol atau tombol tombol biner. Seperti halnya tombol, nilai kotak centang disertakan dalam objek peristiwa tindakan yang diteruskan ke Action yang dilampirkan ke DecoratedText ini oleh setOnClickAction(action) metode.

Nukilan kode berikut menunjukkan cara menentukan widget DecoratedText kotak centang, 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));

Contoh widget kotak centang teks yang dihias

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 yang akan dieksekusi saat nilai alat pilih berubah.

Nukilan kode berikut menunjukkan cara menentukan pemilih tanggal saja, pemilih khusus waktu, dan pemilih waktu tanggal, yang kemudian dapat Anda tambahkan ke kartu:

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

Berikut adalah contoh fungsi pengendali widget pemilih tanggal dan waktu. Pengendali ini hanya memformat dan mencatat string yang mewakili waktu tanggal yang dipilih oleh pengguna dalam widget pemilih tanggal dan 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/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);
  }
}

Tabel di bawah menunjukkan contoh UI pemilihan pemilih di desktop dan perangkat seluler. Saat dipilih, alat pilih tanggal akan membuka UI kalender berbasis bulan untuk memungkinkan pengguna memilih tanggal baru dengan cepat.

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

Desktop	Seluler

Grid

Menampilkan item dalam tata letak multikolom dengan widget petak. Setiap item dapat menampilkan gambar, judul, dan subtitel. Gunakan opsi konfigurasi tambahan untuk menyetel posisi teks relatif terhadap gambar dalam item petak.

Anda dapat mengonfigurasi item petak dengan ID yang ditampilkan sebagai parameter ke tindakan yang ditentukan pada petak.

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

Pemformatan teks

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

Format	Contoh	Hasil yang Dirender
Tebal	`<b>test</b>`	test
Mencetak miring	`<i>test</i>`	test
Garis bawah	`<u>test</u>`	test
Coret	`<s>test</s>`	~~test~~
Warna font	`<font color="#ea9999">test</font>`	test
Hyperlink	`<a href="http://www.google.com">google</a>`	Google
Waktu	`<time>2020-02-16 15:00</time>`	16-02-2020 15.00
Baris baru	`test <br> test`	uji pengujian