Library

Library adalah project skrip yang fungsinya dapat digunakan kembali dalam skrip lain.

Skrip yang menggunakan library tidak berjalan secepat jika semua kode berada dalam satu project skrip. Meskipun library dapat membuat pengembangan dan pemeliharaan lebih praktis, gunakan library dengan hemat dalam proyek yang mengutamakan kecepatan. Karena masalah ini, penggunaan library harus dibatasi di add-on Google Workspace.

Mendapatkan akses ke pustaka

Untuk menyertakan library dalam project, Anda harus memiliki akses tingkat lihat setidaknya ke library tersebut. Jika Anda bukan penulis pustaka yang ingin disertakan, hubungi penulis dan minta akses.

Anda memerlukan ID skrip library yang ingin disertakan. Jika Anda memiliki akses ke library, temukan ID skrip di halaman Project Settings .

Menambahkan library ke project skrip Anda

Di sebelah kiri editor Apps Script, di samping "Library", klik Tambahkan library .
Di kolom "ID skrip", tempelkan ID skrip library.
Klik Cari.
Jika Anda mengalami error, pastikan Anda memiliki akses tingkat lihat ke project yang ingin Anda sertakan.
Klik drop-down Versi, lalu pilih versi library yang akan digunakan.
Periksa apakah nama "ID" default adalah nama yang ingin Anda gunakan dengan library ini. Ini adalah nama yang digunakan skrip Anda untuk merujuk ke library. Misalnya, jika Anda menyetelnya ke Test, lalu memanggil metode library tersebut sebagai berikut: Test.libraryMethod.
Jika Anda menggunakan nama ID yang cocok dengan nama layanan yang sudah ada, seperti MailApp, atau library yang sebelumnya ditambahkan, library yang baru saja Anda tambahkan akan menggantikan layanan atau library yang ada.
Klik Tambahkan.

Menggunakan library

Gunakan library yang disertakan seperti Anda menggunakan layanan default. Misalnya, jika Test adalah ID untuk library Anda, ketik Test yang segera diikuti dengan titik untuk melihat daftar metode di library.

Buka dokumentasi referensi untuk library yang disertakan dengan mengikuti langkah-langkah berikut:

Di sebelah kiri editor skrip, di samping nama pustaka, klik Lainnya > Buka di tab baru.

Menghapus perpustakaan

Di sebelah kiri editor skrip, di samping nama pustaka, klik Lainnya > Hapus > Hapus pustaka.

Jika pustaka dihapus oleh penulis, Anda tetap harus menghapusnya dari daftar pustaka yang disertakan.

Memperbarui koleksi

Ubah versi pustaka atau perbarui ID-nya.

Di sebelah kiri editor, di bagian "Pustaka", klik nama pustaka.
Lakukan perubahan, lalu klik Simpan.

Membuat dan membagikan koleksi

Untuk menggunakan dan membagikan project skrip Anda sebagai library, ikuti langkah-langkah berikut:

Buat deployment versi skrip Anda.
Bagikan akses tingkat lihat setidaknya kepada semua calon pengguna perpustakaan.
Berikan ID skrip kepada pengguna tersebut, yang dapat ditemukan di halaman Setelan Project .

Praktik terbaik

Berikut adalah beberapa panduan yang harus diikuti saat menulis library:

Pilih nama yang bermakna untuk project Anda karena nama ini digunakan sebagai ID default saat library Anda disertakan oleh orang lain.
Agar satu atau beberapa metode skrip Anda tidak terlihat (atau dapat digunakan) oleh pengguna library Anda, akhiri nama metode dengan garis bawah. Misalnya, myPrivateMethod_.
Hanya properti global yang dapat di-enumerasi yang dapat dilihat oleh pengguna pustaka. Hal ini mencakup deklarasi fungsi, variabel yang dibuat di luar fungsi dengan var, dan properti yang ditetapkan secara eksplisit pada objek global. Misalnya, Object.defineProperty() dengan enumerable yang ditetapkan ke false akan membuat simbol yang dapat Anda gunakan di library, tetapi simbol ini tidak dapat diakses oleh pengguna Anda.

Untuk memastikan pengguna library Anda dapat memanfaatkan pelengkapan otomatis editor skrip dan dokumentasi yang dibuat secara otomatis, sertakan dokumentasi gaya JSDoc untuk semua fungsi Anda. Berikut contohnya:

/**
 * Raises a number to the given power, and returns the result.
 *
 * @param {number} base the number we're raising to a power
 * @param {number} exp the exponent we're raising the base to
 * @return {number} the result of the exponential calculation
 */
function power(base, exp) { ... }

Pemberian cakupan resource

Ada dua jenis resource saat Anda bekerja dengan library: bersama dan tidak bersama. Resource bersama berarti bahwa library dan skrip yang menyertakan memiliki akses bawaan ke instance resource yang sama. Diagram berikut menggambarkan resource bersama menggunakan contoh Properti Pengguna:

Sumber Daya Bersama

Resource yang tidak dibagikan berarti library dan skrip yang menyertakan hanya memiliki akses bawaan ke instance resource-nya. Namun, library dapat memberikan akses ke resource yang tidak dibagikan dengan memiliki fungsi eksplisit yang beroperasi di dalamnya. Berikut adalah contoh fungsi yang akan Anda sertakan dalam library untuk mengekspos Properti Skripnya:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

Diagram berikut menggambarkan resource yang tidak dibagikan menggunakan contoh Properti Skrip:

Contoh resource yang tidak dibagikan

Tabel ini mencantumkan resource yang dibagikan dan tidak dibagikan untuk referensi Anda:

Resource	Dibagikan*	Tidak Dibagikan**	Catatan
Kunci			Instance yang sama dapat dilihat oleh semua orang termasuk skrip saat dibuat di pustaka.
Properti Skrip			Instance yang sama dapat dilihat oleh semua orang termasuk skrip saat dibuat di pustaka.
Cache			Instance yang sama dapat dilihat oleh semua orang termasuk skrip saat dibuat di pustaka.
Pemicu			Pemicu sederhana yang dibuat di pustaka tidak dipicu oleh skrip termasuk.
ScriptApp
UiApp
Properti Pengguna
Logger dan transkrip eksekusi
Situs, Spreadsheet, dan penampung lainnya			Panggilan ke `getActive` menampilkan penampung termasuk skrip.
MailApp dan GmailApp
* Artinya, library tidak memiliki instance fitur/resource-nya sendiri dan menggunakan instance yang dibuat oleh skrip yang memanggilnya. ** Artinya, library memiliki instance resource/fitur sendiri dan semua skrip yang menggunakan library tersebut berbagi dan memiliki akses ke instance yang sama.

Menguji library

Untuk menguji pustaka Anda, gunakan deployment head. Siapa pun yang memiliki akses tingkat editor ke skrip dapat menggunakan deployment head.

Anda tetap memerlukan setidaknya satu versi library yang disimpan.

Men-debug library

Saat men-debug skrip yang menyertakan library, Anda tidak dapat menelusuri kode library atau menyetel titik henti sementara di dalamnya. Jika Anda mencoba masuk ke fungsi library dalam mode debug, debugger akan melewati fungsi dan masuk ke baris berikutnya dalam skrip panggilan.

Menggunakan HEAD (Mode Pengembangan) untuk versi library tidak memungkinkan penelusuran ke dalam library atau mencapai titik henti sementara di dalamnya.

Untuk men-debug kode library, gunakan salah satu metode berikut:

Men-debug dari project library: Buka project skrip library di editor Apps Script. Untuk menguji fungsi library dengan argumen tertentu, buat fungsi "pengujian" sementara dalam project library yang memanggil fungsi library Anda, lalu jalankan fungsi pengujian tersebut dalam mode debug.
Logging: Gunakan console.log() dalam fungsi library Anda untuk menampilkan informasi ke log eksekusi. Saat dipanggil oleh skrip lain, log ini akan muncul di log eksekusi skrip yang memanggil.