Panduan gaya UI untuk Add-on Editor

Add-on Editor membuat antarmuka pengguna (menu, sidebar, dan dialog) menggunakan layanan HTML Apps Script. Karena antarmuka dikembangkan dalam HTML dan CSS, antarmuka tersebut sangat mudah disesuaikan. Namun, saat mem-build antarmuka add-on, Anda harus mendesainnya untuk memberikan pengalaman pengguna yang baik.

Add-on terbaik memperluas setiap editor secara alami menggunakan kontrol dan perilaku yang sudah dikenal. Saat membuat add-on baru:

Teks

Nama add-on

Anda harus menetapkan nama add-on saat memublikasikannya. Nama ini muncul di banyak tempat, seperti toko add-on dan dalam menu.

  • Gunakan kapitalisasi judul.
  • Hindari tanda baca, terutama tanda kurung, kecuali merupakan bagian dari merek Anda.
  • Buat judul yang singkat—30 karakter atau kurang adalah pilihan terbaik. Nama panjang dapat terpotong secara otomatis.
  • Jangan sertakan nama produk Google yang menjadi tujuan add-on (atau gunakan kata Google).
  • Tinggalkan informasi versi.
  • Pastikan nama add-on yang dipublikasikan sama dengan nama file project skrip. Nama project akan muncul dalam dialog otorisasi.
Larangan Anjuran
Nama add-on salah Nama add-on yang bagus

Gaya penulisan

Anda tidak perlu menulis banyak. Sebagian besar tindakan harus dijelaskan melalui ikonografi, tata letak, dan label singkat. Jika Anda merasa sebagian add-on memerlukan penjelasan yang lebih lengkap daripada yang dapat diberikan oleh label singkat, praktik terbaik adalah membuat halaman web terpisah yang mendeskripsikan add-on Anda dan menautkan ke add-on tersebut.

Saat menulis teks UI:

  • Gunakan kapitalisasi kalimat (terutama untuk tombol, label, dan item menu).
  • Pilih teks singkat dan sederhana tanpa jargon atau akronim.
Larangan Anjuran

Tips pasca-penginstalan

Tips pascapenginstalan akan muncul tepat setelah seseorang menginstal add-on, dan juga muncul di Bantuan. Anda memiliki beberapa kalimat untuk membantu pengguna memulai dengan cepat.

  • Mulai dengan kata tindakan.
  • Jelaskan langkah pertama untuk menggunakan add-on Anda.
  • Jika Anda memiliki UI utama, seperti sidebar, jelaskan cara membukanya.
  • Jangan mempromosikan add-on di sini karena add-on sudah terinstal.
Larangan Anjuran
Tips pasca-penginstalan yang buruk Kiat pasca-penginstalan yang baik

Tidak seperti project Apps Script reguler, add-on tidak muncul di editor skrip atau pengelola skrip; pengguna tidak dapat menjalankan skrip add-on secara langsung. Sebagai gantinya, setiap add-on mendapatkan tempat di menu add-on. Menu (dan mungkin dialog atau sidebar) memungkinkan pengguna berinteraksi dengan add-on.

  • Menu adalah bagian penting dari cara pengguna mengontrol add-on Anda, jadi desain struktur dan susunan katanya dengan hati-hati.
  • Hindari item menu yang hanya mengulangi nama add-on Anda. Mulailah dengan kata tindakan.
  • Jika item menu utama Anda memulai alur kerja dan tidak ada kata kerja tunggal yang menjelaskan fungsi item menu utama, beri nama "Start". Pola ini digunakan di panduan memulai add-on Dokumen.
  • Kecuali jika menu Anda memiliki lebih dari enam item, cobalah untuk tidak menggunakan sub-menu. Mereka bisa menjadi rumit dan sulit untuk dipilih.
  • Jelaskan tugas, bukan komponen UI yang ditampilkan item menu.
Larangan Anjuran
Label item menu buruk Label item menu yang baik

Pesan error

Ketika terjadi kesalahan, penting untuk menggunakan bahasa yang sederhana. Jelaskan masalah dari sudut pandang pengguna, dan sarankan cara memperbaikinya.

  • Jangan izinkan pengguna melihat pengecualian yang ditampilkan kode Anda. Sebagai gantinya, gunakan pernyataan try...catch untuk menangkap pengecualian, lalu tampilkan pesan error pengguna dengan teks inline yang telah diberi gaya di class error dari paket CSS add-on atau dialog pemberitahuan.
  • Sebelum memublikasikan, pastikan add-on Anda tidak mencatat log informasi debug ke konsol JavaScript. Sebagai gantinya, gunakan logging Stackdriver.
Larangan Anjuran
Pesan error buruk Pesan error baik

Konten Bantuan

Setiap menu add-on menyertakan dialog Bantuan otomatis. Jika Anda memberikan URL bantuan saat memublikasikan, tombol "Pelajari lebih lanjut" akan ditautkan ke halaman tersebut. Kecuali jika add-on Anda sudah jelas, sediakan halaman yang menjelaskan cara menggunakannya.

  • Jika memungkinkan, tampilkan petunjuk dalam daftar berbutir atau bernomor. Memandu pengguna sampai ke hasil akhir, dengan referensi yang jelas ke elemen UI yang diberi nama.
  • Pastikan petunjuk Anda menerangkan persyaratan apa pun dengan jelas, seperti menyiapkan spreadsheet dengan cara tertentu.
  • Jangan ragu untuk menautkan ke konten bantuan dari antarmuka pengguna utama. Jika add-on membuat dokumen baru, Anda juga dapat menampilkan petunjuk di bagian isi dokumen.

Antarmuka pengguna khusus

Beberapa Add-on Editor sederhana dapat dikontrol sepenuhnya oleh menunya, tetapi sebagian besar menampilkan sidebar atau dialog dengan konten kustom.

  • Sidebar paling cocok untuk alat persisten yang cenderung digunakan orang berulang kali saat merujuk pada konten dokumen atau spreadsheet mereka.
  • Dialog paling cocok untuk alat sekali pakai, halaman setelan, dan pesan penting.

Teks UI

Dalam dialog atau sidebar mana pun, anggaplah orang hanya membaca label judul dan tombol. Apakah mereka masih dapat mengetahui apa yang dilakukan antarmuka Anda dan membuat pilihan yang baik?

  • Gunakan judul dan label tombol yang berdiri sendiri.
  • Hindari blok teks deskriptif yang panjang.

Dialog

Dialog sangat bagus untuk alat yang digunakan orang sekali saja, lalu lanjutkan. Misalnya, jika add-on Anda memungkinkan orang menyisipkan gambar, Anda dapat menampilkan dialog dengan pilihan yang akan disisipkan ? lalu menutup dialog saat grafik disisipkan. Dialog juga berguna untuk menampilkan setelan add-on, atau untuk menyampaikan pesan penting.

  • Jangan membuka dialog (termasuk pemberitahuan atau perintah) dari dialog lain—hanya tampilkan satu per satu.
  • Untuk judul dialog, gunakan kata atau frasa pendek, yang diawali dengan kata paling penting.
  • Label tombol harus terkait dengan judul dialog.
  • Pilih dua tombol, biasanya tindakan utama dan "Cancel". Untuk kasus khusus yang memerlukan tombol ketiga, pertimbangkan bagian pojok kanan bawah.
  • Menempatkan tombol di pojok kiri bawah dialog. Tombol utama berwarna biru harus berada di sebelah kiri, dengan tombol sekunder abu-abu di sebelah kanan.
Larangan Anjuran
Judul dialog salah Judul dialog yang bagus

Sidebar memungkinkan orang merujuk kembali ke dokumen, spreadsheet, presentasi, atau formulir saat membuat pilihan. Opsi ini juga memungkinkan orang menggunakan add-on Anda berulang kali. Setiap kali sidebar baru dibuka, sidebar sebelumnya akan ditutup secara otomatis. Opsi ini paling baik untuk mode sementara di mana pengguna keluar setelah selesai.

  • Pengguna mungkin memiliki add-on lain dengan sidebar mereka sendiri. Jika dua add-on mencoba membuka sidebar secara bersamaan, hanya satu yang akan ditampilkan.
  • Jangan menampilkan sidebar atau dialog saat dokumen pertama kali dibuka.
  • Hanya add-on yang beroperasi di AuthMode.FULL yang dapat membuka sidebar atau dialog. Anda dapat menggunakan item menu untuk membuka sidebar karena tindakan ini akan meminta pengguna untuk memberikan otorisasi penuh.

Kontrol

UI add-on yang bagus memberikan ruang kosong untuk kontrol mereka. Margin dan padding yang memadai sangat membantu, sedangkan kontrol padat dapat tampak berlebihan. Jika ragu, pinjam tata letak dari editor itu sendiri. Misalnya, tinjau dialog yang ada di Google Dokumen, seperti File > Penyiapan halaman, saat membuat dialog Anda sendiri.

Dokumentasi untuk paket CSS add-on menyediakan markup contoh untuk setiap jenis kontrol di bawah.

Tombol

Gunakan tombol untuk mengontrol tindakan utama antarmuka pengguna Anda, bukan link biasa atau elemen lainnya.

  • Hindari menampilkan lebih dari satu tombol biru, merah, atau hijau secara bersamaan. Tombol abu-abu dapat muncul berulang kali.
  • Sebagian besar label tombol harus dalam kapitalisasi kalimat dan dimulai dengan kata kerja. Tombol merah, biasanya untuk tindakan pembuatan, harus menggunakan huruf besar semua.
Larangan Anjuran

Kotak centang dan tombol pilihan

Gunakan kotak centang ketika orang dapat memilih beberapa opsi, atau tidak ada opsi sama sekali. Gunakan tombol pilihan (atau menu pilih) saat tepat satu opsi harus dipilih.

  • Jangan ubah perilaku kotak centang untuk meniru tombol pilihan.
  • Tidak langsung melakukan apa pun saat mereka diperiksa. Orang membuat kesalahan. Tunggu hingga pengguna mengklik tombol untuk mengonfirmasi pilihan mereka.

Pilih menu

Pilihan{i> <i}adalah cara yang bagus untuk memberikan sebuah daftar singkat alternatif.

  • Urutkan opsi menurut abjad atau skema logis yang dapat dipahami semua pengguna (seperti hari, mulai dari hari Minggu).
  • Jika daftar terlalu panjang, pertimbangkan untuk menggunakan kontrol lain. Misalnya, Anda dapat menampilkan daftar yang dapat di-scroll untuk memberi menu lebih banyak ruang dan membuatnya lebih mudah dinavigasi.

Area teks

Jika orang perlu mengetik lebih dari beberapa kata, gunakan area teks.

  • Buat area teks setinggi minimal dua baris agar lebih mudah digunakan dan tidak terlihat seperti kolom teks.
  • Tempatkan label di bagian atas.

Kolom teks

Gunakan kolom teks jika orang hanya perlu mengetik satu atau dua kata.

  • Lebar kolom teks akan menunjukkan tulisan yang Anda harapkan akan diketik.
  • Hindari penggunaan teks placeholder sebagai label, karena teks tersebut akan hilang saat difokuskan. Teks placeholder berguna untuk memberikan contoh atau detail tambahan.
  • Tempatkan label di atas, tetapi Anda dapat mengatur tata letak kolom teks pendek secara berdampingan.

Branding

Di add-on Anda

Jika Anda ingin menyertakan branding, buat judul yang singkat dan ringan. Hal ini membantu orang berfokus pada UI Anda, dan membuat add-on terasa seperti bagian dari editor.

  • Semua aspek add-on Anda harus mengikuti pedoman branding.
  • Jangan menyertakan kata “Google” atau menggunakan ikon produk Google.
  • Teks tidak boleh berisi lebih dari beberapa kata dan diberi gaya dalam class gray dari paket CSS add-on.
  • Gambar harus menggunakan latar belakang putih dan tidak lebih dari 200 × 60 px.
  • Untuk dialog, branding harus berada di pojok kanan bawah.
  • Untuk sidebar, branding bisa di bagian atas atau bawah.

Di toko

Untuk memublikasikan Add-on Editor, Anda memerlukan sejumlah aset gambar. Aset ini digunakan untuk membuat listingan Play Store add-on.

  • Semua aspek listingan Play Store Anda harus mengikuti pedoman branding.
  • Untuk detail selengkapnya tentang gambar yang perlu Anda berikan, lihat panduan gambar.

Aksesibilitas

Semua orang harus dapat menikmati add-on, baik melihat warna secara berbeda, menggunakan pembaca layar, atau memiliki kebutuhan lainnya. Aksesibilitas adalah topik yang luas yang tidak dapat dibahas sepenuhnya dalam panduan gaya ini. Salah satu referensi yang bermanfaat adalah situs Google Accessibility. Namun, berikut beberapa tips untuk memulai:

  • Pastikan Anda dapat membuka semua kontrol UI dengan keyboard. Tambahkan tabindex=0 ke kontrol kustom (seperti yang dibuat dengan <div>) sehingga orang dapat menekan tombol tab ke kontrol tersebut. Pertimbangkan apakah kunci lain juga harus didukung, seperti panah untuk daftar.
  • Beberapa orang mungkin menggunakan pembaca layar dengan add-on Anda. Dengan demikian, gambar harus memiliki atribut alt, dan kontrol kustom harus memiliki atribut ARIA untuk mendeskripsikan penggunaannya.
  • Jangan hanya mengandalkan warna untuk mengomunikasikan status. Gunakan juga ikon dan teks.

Jika Anda menggunakan kontrol web standar, seperti yang dijelaskan sebelumnya dalam panduan ini, membuat add-on Anda dapat diakses menjadi lebih mudah.