擴充 Google 文件

Google Apps Script 可讓您透過程式建立和修改 Google 文件，並使用新選單、對話方塊和側欄自訂使用者介面。

基本概念

Apps Script 可與 Google 文件互動：如要在 Google 文件中建立容器繫結的指令碼，請依序按一下「擴充功能」>「Apps Script」。

無論是哪種情況，都能透過 Apps Script 的文件服務輕鬆與 Google 文件互動，如以下範例所示。

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.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);
}

上述指令碼會在使用者的 Google 雲端硬碟中建立新文件，然後插入含有與文件名稱相同文字的段落、將段落設為標題的樣式，再根據二維陣列中的值附加資料表。指令碼就像將 DocumentApp.create() 呼叫替換為 DocumentApp.openById() 或 openByUrl()，就能輕鬆對現有文件做出這些變更。如果是在文件 (容器繫結) 中建立的指令碼，請使用 DocumentApp.getActiveDocument()。

文件結構

從 Apps Script 的角度來看，Google 文件的結構與 HTML 文件非常類似，亦即 Google 文件是由通常包含其他元素的元素 (例如 Paragraph 或 Table) 組成。修改 Google 文件的大多數指令碼開頭都是呼叫 getBody()，因為 Body 是包含 HeaderSection、FooterSection 和任何 Footnotes 以外的所有其他元素。

不過，其他元素類型可以包含其他類型的相關規則。此外，Apps Script 中的文件服務只能插入特定類型的元素。以下樹狀圖顯示了特定類型的元素可包含哪些元素。

可以插入以粗體顯示的元素；非粗體元素只能調整。

取代文字

Apps Script 常用於取代 Google 文件中的文字。假設您有一份包含用戶端資訊的試算表，並想為每個客戶產生個人化的 Google 文件。(這類作業通常稱為郵件合併)。

取代文字的方法有很多種，但最簡單的方法是使用以下範例中顯示的 replaceText() 方法。replaceText 支援大部分的 JavaScript 規則運算式功能。下方的第一個函式會在 Google 文件中新增幾行預留位置文字；在實際環境中，您可能會想要自行在文件中輸入預留位置。第二個函式會將預留位置取代為 client 物件中定義的屬性。

請注意，這兩種函式都使用 getActiveDocument() 方法，這僅適用於在 Google 文件中建立的指令碼；在獨立指令碼中，請改用 DocumentApp.create()、openById() 或 openByUrl()。

新增一些預留位置

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

取代預留位置

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .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);
}

自訂選單和使用者介面

您可以透過新增選單、對話方塊和側欄來自訂 Google 文件。不過請注意，只有在指令碼已「繫結」與文件的情況下，指令碼才能與目前開啟文件的使用者介面互動。

瞭解如何在 Google 文件中加入自訂選單和對話方塊。如要進一步瞭解如何為對話方塊或側欄建立自訂介面，請參閱 HTML 服務指南。如果您打算以外掛程式形式發布自訂介面，請按照樣式指南中的操作說明，與 Google 文件編輯器的樣式和版面配置保持一致。

Google 文件外掛程式

外掛程式會在 Google 文件內執行，可以從 Google 文件外掛程式商店安裝。如果您已為 Google 文件開發指令碼，並且想要與全世界共用，則可使用 Apps Script 以外掛程式的形式publish指令碼，讓其他使用者可從外掛程式商店安裝。

如要瞭解如何建立 Google 文件外掛程式，請參閱建構 Google 文件外掛程式的快速入門導覽課程。

觸發條件

繫結至 Google 文件的指令碼可使用簡易觸發條件回應文件的 onOpen 事件，每當具有編輯權限的使用者在 Google 文件中開啟文件時，就會發生這個事件。

如要設定觸發條件，只要編寫名為 onOpen() 的函式即可。如需這項觸發條件的範例，請參閱「Google Workspace 中的自訂選單」。雖然簡易觸發條件對於新增選單很有用，但仍無法使用任何需要授權的 Apps Script 服務。