Pengodean skrip pertama Anda: Fungsi khusus

Seperti kebanyakan aplikasi spreadsheet, Google Sheets memiliki sejumlah fungsi formula bawaan seperti =SUM()yang memungkinkan penghitungan cepat pada data spreadsheet. Fungsi khusus hanyalah fungsi yang Anda tetapkan sendiri, menggunakan Apps Script. Setelah Anda mendefinisikan fungsi khusus, Anda dapat menggunakannya di mana saja di spreadsheet Anda, seperti fungsi bawaan.

Bagian ini menunjukkan kepada Anda cara membuat fungsi khusus di Script Aplikasi yang melakukan konversi moneter.

Membuat file skrip baru

Dengan proyek spreadsheet dan skrip yang sama seperti yang digunakan di bagian Makro, Anda dapat mengikuti instruksi ini untuk mempelajari cara membuat skrip baru (yang nantinya bisa Anda gunakan untuk membuat fungsi kustom pertama Anda!):

  1. Di editor skrip, pilih File> Baru> File skrip .
  2. Beri nama file skrip baru customFunctions(Skrip Aplikasi secara otomatis menambahkan .gsekstensi nama file skrip).

Tab baru bernama customFunctions.gsdalam editor akan muncul:

Setiap kali Anda membuat skrip baru, editor secara otomatis menghasilkan default myFunction()untuk kenyamanan Anda.

Sekarang Anda telah membuat skrip khusus untuk fungsi kustom, Anda dapat mengisinya dengan kode.

Konversi dolar AS ke franc Swiss

Misalkan Anda ingin menyesuaikan data untuk ‘Sepuluh Film Terlaris Tertinggi 2018’ untuk menunjukkan tidak hanya nilai kotor dalam dolar AS tetapi juga dalam franc Swiss. Dengan fungsi khusus, Anda dapat melakukannya dengan mudah. Latihan berikut menunjukkan cara membuat fungsi kustom untuk secara matematis mengonversi nilai dolar Anda ke nilai franc.

Sebelum Anda dapat menulis fungsi khusus pertama Anda, sesuaikan set data Anda untuk memungkinkan fungsi mendemonstrasikan output yang tepat. Untuk melakukan ini:

  1. Di Lembar, klik kanan kolom H .
  2. Di menu yang dihasilkan, klik Insert 1 right .
  1. Beri label pada kolom “Worldwide_Gross (franc Swiss)” di sel I1 .

Sekarang Anda memiliki kolom yang dapat menyimpan hasil fungsi kustom konversi Anda. Selanjutnya, Anda dapat menggunakan editor skrip untuk membuat fungsi kustom pertama Anda!

  1. Di customFunction.gs, ganti kode untuk myFunction()dengan kode berikut:
/**
 * Converts US dollars to Swiss francs.
 * 
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The converted total of Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Ini adalah kode yang akan mengkonversi dolar AS ke franc Swiss. Coba instruksi di bawah ini, dan lihat bagaimana Anda dapat menjalankan fungsi kustom dalam lembaran.

  1. Pilih File> Simpan , atau Ctrl + S ( Cmd + S pada Mac) untuk menyimpan skrip Anda.
  2. Di Lembar, pilih sel I2 .
  3. Di bilah fungsi, masukkan =USDTOCHF(H2).

Untuk menerapkan rumus ke seluruh sel di kolom:

  1. Pindahkan kursor Anda ke sudut kanan bawah sel I2 dan pilih kotak biru kecil (kursor Anda akan berubah menjadi ketika melayang di atas kotak biru).
  2. Klik dan seret kotak biru ke bawah untuk menyorot I3 : I11 .

Kolom I sekarang mencantumkan konversi franc Swiss dari nilai dolar AS kolom G!

Selamat, Anda telah membuat fungsi kustom pertama Anda. Bagian selanjutnya menjelaskan kode yang terdiri USDTOCHF().

Menganalisis fungsi USDTOCHF()

Mulai dari awal kode, Anda dapat mengenali komentar yang merinci tujuan kode:

/**
 * Converts US dollars to Swiss francs.
 * 
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */

Blok komentar seperti ini sering digunakan dalam pemrograman untuk menjelaskan fungsi apa yang dilakukan.

Dalam komentar ini, Anda dapat mengidentifikasi dua bagian: deskripsi fungsi (untuk mengonversi dolar menjadi franc) dan anotasi yang menjelaskan parameter fungsi dan jenis pengembalian.

Dengan anotasi, Apps Script menggunakan JSDoc untuk membantu Anda mendokumentasikan dan membuat petunjuk pelengkapan otomatis untuk kode Anda. Anda dapat membaca di bawah ini bagaimana setiap anotasi yang digunakan USDTOCHF()membantu Anda dengan pengembangan Skrip Aplikasi Anda:

  • @param: Anda dapat menggunakan @paramanotasi untuk menjelaskan setiap parameter yang diteruskan ke fungsi.
  • @return: Anda dapat menggunakan @returnanotasi untuk menggambarkan apa fungsi kembali.
  • @customfunction: Anda harus selalu menambahkan @customfunctionkomentar dokumen fungsi kustom apa pun. Anotasi ini memberi tahu Sheets untuk melengkapi fungsi kustom Anda secara otomatis sama seperti Sheets autocompletes fungsi bawaan ketika Anda mengetikkan nama fungsi di dalam sel seperti yang terlihat di bawah ini:

Perhatikan bahwa teks yang muncul dalam pop-up pelengkapan otomatis persis sama dengan teks deskripsi yang Anda tempatkan di blok komentar. Anda dapat membuat fungsi kustom Anda lebih mudah digunakan dengan memastikan bahwa deskripsi yang Anda buat ditulis dengan baik dan lengkap.

Selanjutnya, fokus pada kode dalam fungsi USDTOCHF():

function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Seperti disebutkan sebelumnya, USDTOCHF()mengambil variabel numerik dolar, dan mengembalikan nilai yang dikonversi ke franc Swiss dalam variabel numerik swissFrancsdengan mengalikannya dengan kurs tetap. Parameter input adalah nilai yang terkandung dalam sel yang Anda tentukan saat menambahkan fungsi kustom ke sel. Dalam contoh ini, jumlah dolar input berasal dari kolom H. Nilai output swissFrancsditempatkan di sel fungsi (yaitu, kolom I dalam contoh ini).

Fungsi khusus dapat berfungsi dengan nilai numerik atau string, seperti yang akan Anda lihat di bagian selanjutnya.

Menggabungkan awalan string

Misalkan Anda ingin output numerik fungsi USDTOCHF()menyertakan awalan franc Swiss CHF. Anda dapat melakukannya dengan Apps Script dengan menggunakan operator gabungan ( +,seperti yang ditunjukkan dalam instruksi berikut:

  1. Di editor skrip, ubah return varpada baris 10 ke return 'CHF' + swissFrancs.

The +Operator menambahkan string CHFke depan nilai yang terkandung dalam swissFrancs. Kode Anda sekarang akan terlihat seperti ini:

/**
 * Converts US dollars to Swiss francs.
 * 
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return 'CHF' + swissFrancs;
}

Tinjau langkah-langkah di bawah ini, sehingga Anda dapat menyimpan dan menjalankan fungsi Anda untuk melihat hasilnya!

  1. Pilih File> Simpan , atau Ctrl + S ( Cmd + S pada Mac) untuk menyimpan skrip Anda.

Franc Swiss sekarang mengawali nilai-nilai kolom I:

Anda telah memperbarui fungsi kustom Anda yang sekarang tidak hanya mengonversi dolar AS ke franc Swiss tetapi juga menghasilkan mata uang dengan awalan string.

Advanced: Mengambil data eksternal

Ini adalah awal yang baik untuk fungsi kustom dasar, tetapi contoh ini mengasumsikan bahwa nilai tukar dolar untuk franc Swiss adalah konstan. Seandainya Anda ingin agar nilai tukar saat ini selalu digunakan, sehingga setiap kali lembar dimuat kembali, nilai akan dihitung ulang untuk mewakili konversi saat ini? Untuk melakukan itu, Anda perlu sarana untuk mengetahui apa nilai tukar saat ini. Itu bukan informasi yang tersedia di Google Sheets, tetapi untungnya Anda dapat menggunakan Apps Script untuk mendapatkannya!

Anda dapat menggunakan kode seperti di bawah ini untuk mendapatkan tingkat konversi franc Swiss ke dolar AS saat ini:

function USDTOCHF(dollars){
  // Gets a cache that is common to all users of the script.
  var cache = CacheService.getScriptCache();

  // Accesses the memory location (rates.CHF) of the script cache. 
  var rate = cache.get('rates.CHF');

  // If a cache miss occurs, the program fetches the current
  // CHF rate from an API and stores that rate in the cache
  // for later convenience. 
  if (!rate) {
    var response =
UrlFetchApp.fetch('https://api.exchangeratesapi.io/latest?base=USD');
    var result = JSON.parse(response.getContentText());
    rate = result.rates.CHF;
    cache.put('rates.CHF', rate);
  }
  // Converts dollars to CHF according to the latest rate. 
  var swissFrancs = dollars * rate;
  // Returns the CHF value. 
  return 'CHF' + swissFrancs;
}

Kode ini mengambil nilai tukar saat ini dari server informasi keuangan menggunakan API nilai tukar pihak ketiga . Ini dilakukan menggunakan layanan Apps Script seperti UrlFetchAppdan CacheService. Konsep-konsep canggih tersebut berada di luar cakupan codelab khusus ini, tetapi Anda dapat mulai melihat fleksibilitas dari Script Aplikasi mengotomatisasi tugas-tugas kompleks di Google Sheets.

Pedoman fungsi khusus

Selamat telah menyelesaikan latihan untuk fungsi-fungsi khusus. Saat Anda menggunakan fungsi khusus dalam proyek Anda, penting untuk dipahami bahwa mereka memiliki batasan tertentu. Daftar berikut ini merangkum batasan-batasan yang dirinci dalam panduan Fungsi Kustom dalam Google Sheets :

  • Jangan membuat fungsi khusus yang memerlukan otorisasi pengguna . Alih-alih, bangun fungsi khusus untuk memenuhi tugas yang lebih sederhana seperti contoh kalkulasi data, pengeditan teks, dll. Lihat Menggunakan layanan Aplikasi Script .
  • Jangan beri nama fungsi khusus sama dengan fungsi bawaan lainnya, atau akhiri nama dengan garis bawah. Lihat pedoman Penamaan .
  • Jangan berikan argumen variabel ke fungsi kustom. Anda hanya bisa memberikan nilai deterministik (nilai tetap) ke fungsi khusus sebagai argumen. Melewati argumen variabel, seperti hasil =RAND(), akan merusak fungsi kustom. Lihat pedoman Argumen .
  • Jangan membuat fungsi yang membutuhkan waktu lebih dari 30 detik untuk diselesaikan. Jika butuh waktu lebih lama akan terjadi kesalahan, jadi pertahankan kode fungsi sederhana dan terbatas ruang lingkupnya. Yang terbaik adalah menjaga penghitungan yang dilakukan dalam fungsi kustom sesederhana mungkin. Lihat pedoman Pengembalian nilai .

Sekarang Anda memiliki kemampuan untuk meningkatkan spreadsheet Anda dengan menggunakan editor skrip untuk bekerja dengan makro dan membuat fungsi kustom! Di bagian berikutnya dan terakhir, Anda dapat meninjau apa yang telah Anda pelajari, dan apa yang dapat Anda lakukan selanjutnya untuk meningkatkan keterampilan menulis Anda.

Leave a Reply

Your email address will not be published. Required fields are marked *