Perluas Google Dokumen

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

Dasar-dasar

Apps Script dapat berinteraksi dengan Dokumen dalam dua cara luas: 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 Dokumen, klik Ekstensi > Apps Script.

Dalam kedua kasus tersebut, Anda dapat berinteraksi dengan dokumen Dokumen menggunakan Layanan Dokumen Apps Script, seperti yang ditunjukkan dalam 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 sebelumnya 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 paragraf tersebut sebagai judul, dan menambahkan tabel berdasarkan nilai dalam array dua dimensi. Skrip juga dapat 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 Dokumen terstruktur 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 lain. Sebagian besar skrip yang mengubah dokumen 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 berikut menunjukkan elemen yang dapat dimuat oleh jenis elemen tertentu.

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

Ganti teks

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

Anda dapat mengganti teks menggunakan metode replaceText, yang mendukung sebagian besar fitur ekspresi reguler JavaScript. Pada contoh berikut, fungsi pertama menambahkan teks placeholder ke dokumen, dan fungsi kedua mengganti teks tersebut dengan properti dari objek client.

Kedua fungsi ini menggunakan metode getActiveDocument dan getActiveTab, yang hanya berlaku untuk skrip yang dibuat di dalam dokumen 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 Dokumen dengan menambahkan menu kustom, kotak dialog, dan sidebar. Perlu diingat bahwa skrip hanya dapat berinteraksi dengan UI dokumen yang terikat dengannya.

Untuk mempelajari lebih lanjut cara membuat antarmuka kustom dengan HTML dan CSS, lihat panduan untuk Layanan HTML. Jika Anda berencana memublikasikan antarmuka sebagai add-on, ikuti panduan gaya untuk memastikan tampilannya konsisten dengan editor Dokumen.

Add-on untuk Dokumen

Add-on berjalan di dalam Dokumen dan dapat diinstal dari toko add-on Dokumen. Jika Anda telah mengembangkan skrip untuk 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 membuat add-on untuk 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 Dokumen.

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