Memperluas Google Dokumen

Google Apps Script memungkinkan Anda membuat dan mengubah Google Dokumen secara terprogram, serta menyesuaikan antarmuka pengguna dengan menu, kotak dialog, dan sidebar baru.

Dasar-dasar

Apps Script dapat berinteraksi dengan Google Dokumen dalam dua cara umum: skrip apa pun dapat membuat atau mengubah dokumen jika pengguna skrip memiliki izin yang sesuai untuk dokumen tersebut, dan skrip juga dapat terikat ke dokumen, yang memberi skrip kemampuan khusus untuk mengubah antarmuka pengguna atau merespons saat dokumen dibuka. Untuk membuat skrip terikat penampung dari dalam Google Dokumen, klik Ekstensi > Apps Script.

Dalam kedua kasus tersebut, berinteraksi dengan dokumen Google Dokumen melalui Layanan Dokumen Apps Script sangatlah mudah, seperti yang ditunjukkan oleh contoh berikut.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

Skrip di atas membuat dokumen baru di Google Drive pengguna, lalu mengambil tab dengan ID t.0 (tab pertama default), menyisipkan paragraf yang berisi teks yang sama dengan nama dokumen, menata gaya paragraf tersebut sebagai heading, dan menambahkan tabel berdasarkan nilai dalam array dua dimensi. Skrip dapat dengan mudah membuat perubahan ini pada dokumen yang ada dengan mengganti panggilan ke DocumentApp.create() dengan DocumentApp.openById() atau openByUrl(). Untuk skrip yang dibuat di dalam dokumen (terikat dengan penampung), gunakan DocumentApp.getActiveDocument() dan Document.getActiveTab().

Struktur dokumen

Dari perspektif Apps Script, dokumen Google Dokumen disusun mirip seperti dokumen HTML—yaitu, dokumen terdiri dari satu atau beberapa objek Tab, yang masing-masing berisi elemen (seperti Paragraph atau Table) yang sering kali berisi elemen lainnya. Sebagian besar skrip yang mengubah dokumen Google Dokumen dimulai dengan panggilan ke getTab() dan asDocumentTab() diikuti dengan getBody(), karena Body adalah elemen inti yang berisi semua elemen lain dalam tab, kecuali HeaderSection, FooterSection, dan Footnotes.

Namun, ada aturan tentang jenis elemen yang dapat berisi jenis lainnya. Selain itu, Layanan Dokumen di Apps Script hanya dapat menyisipkan jenis elemen tertentu ke dalam elemen lain. Struktur di bawah menunjukkan elemen mana yang dapat dimuat oleh jenis elemen tertentu.

Elemen yang ditampilkan dalam huruf tebal dapat disisipkan; elemen yang tidak ditampilkan dalam huruf tebal hanya dapat dimanipulasi di tempat.

Mengganti teks

Apps Script sering digunakan untuk mengganti teks di Google Dokumen. Misalkan Anda memiliki spreadsheet yang berisi informasi klien dan Anda ingin membuat Google Dokumen yang dipersonalisasi untuk setiap klien. (Jenis operasi ini sering disebut sebagai gabungan surat.)

Ada banyak cara untuk mengganti teks, tetapi yang paling sederhana adalah metode replaceText() yang ditunjukkan dalam contoh di bawah. replaceText mendukung sebagian besar fitur ekspresi reguler JavaScript. Fungsi pertama di bawah menambahkan beberapa baris teks placeholder ke Google Dokumen; di dunia nyata, Anda lebih cenderung mengetik placeholder ke dalam dokumen sendiri. Fungsi kedua menggantikan placeholder dengan properti yang ditentukan dalam objek client.

Perhatikan bahwa kedua fungsi ini menggunakan metode getActiveDocument() dan getActiveTab(), yang hanya berlaku untuk skrip yang dibuat di dalam dokumen Google Dokumen; dalam skrip mandiri, gunakan DocumentApp.create(), openById(), atau openByUrl(), yang dikombinasikan dengan Document.getTab(), sebagai gantinya.

Tambahkan beberapa placeholder

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

Ganti placeholder

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

Menu kustom dan antarmuka pengguna

Anda dapat menyesuaikan Google Dokumen dengan menambahkan menu, kotak dialog, dan sidebar. Namun, perlu diingat bahwa skrip hanya dapat berinteraksi dengan UI untuk instance dokumen terbuka saat ini, dan hanya jika skrip terikat ke dokumen.

Lihat cara menambahkan menu kustom dan dialog ke Google Dokumen Anda. Untuk mempelajari lebih lanjut cara membuat antarmuka kustom untuk dialog atau sidebar, lihat panduan untuk Layanan HTML. Jika Anda berencana memublikasikan antarmuka kustom sebagai bagian dari add-on, ikuti panduan gaya untuk konsistensi dengan gaya dan tata letak editor Google Dokumen.

Add-on untuk Google Dokumen

Add-on berjalan di dalam Google Dokumen dan dapat diinstal dari toko add-on Google Dokumen. Jika Anda telah mengembangkan skrip untuk Google Dokumen dan ingin membagikannya kepada dunia, Apps Script memungkinkan Anda memublikasikan skrip sebagai add-on sehingga pengguna lain dapat menginstalnya dari toko add-on.

Untuk melihat cara membuat add-on untuk Google Dokumen, lihat panduan memulai untuk membuat add-on Dokumen.

Pemicu

Skrip yang terikat ke Dokumen Google dapat menggunakan pemicu sederhana untuk merespons peristiwa onOpen dokumen, yang terjadi setiap kali pengguna yang memiliki akses edit ke dokumen membukanya di Google Dokumen.

Untuk menyiapkan pemicu, cukup tulis fungsi yang disebut onOpen(). Untuk contoh pemicu ini, lihat Menu kustom di Google Workspace. Meskipun berguna untuk menambahkan menu, pemicu sederhana tidak dapat menggunakan layanan Apps Script yang memerlukan otorisasi.