擴充 Google 文件

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

基本概念

Apps Script 可以透過兩種方式與 Google 文件互動：如果指令碼使用者擁有文件的適當權限，任何指令碼都可以建立或修改文件；此外，指令碼也可以繫結至文件，讓指令碼具備特殊能力，可變更使用者介面或在開啟文件時回應。如要在 Google 文件中建立容器繫結指令碼，請依序按一下「擴充功能」>「Apps Script」。

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

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);
}

上述指令碼會在使用者的 Google 雲端硬碟中建立新文件，然後擷取 ID 為 t.0 的索引標籤 (預設的第一個索引標籤)，插入包含與文件名稱相同文字的段落，將該段落設為標題，並根據二維陣列中的值附加資料表。只要將對 DocumentApp.create() 的呼叫替換為 DocumentApp.openById() 或 openByUrl()，指令碼就能輕鬆對現有文件進行這些變更。如果是在文件內建立的指令碼 (容器綁定)，請使用 DocumentApp.getActiveDocument() 和 Document.getActiveTab()。

文件結構

從 Apps Script 的角度來看，Google 文件的結構與 HTML 文件相似，也就是說，文件由一或多個 Tab 物件組成，每個物件都包含元素 (例如 Paragraph 或 Table)，而這些元素通常會包含其他元素。大多數修改 Google 文件的程式碼都會先呼叫 getTab() 和 asDocumentTab()，然後再呼叫 getBody()，因為 Body 是核心元素，包含分頁中的所有其他元素，但不包含 HeaderSection、FooterSection 和任何 Footnotes。

不過，系統會根據規則決定哪些類型的元素可包含其他類型。此外，Apps Script 中的文件服務只能將特定類型的元素插入其他元素。下方的樹狀圖顯示特定類型的元素可包含哪些元素。

您可以插入粗體顯示的元素，但粗體以外的元素只能在原地操作。

替換文字

Apps Script 通常用於取代 Google 文件中的文字。假設你有一個充滿客戶資訊的試算表，而且想要為每位客戶產生個人化的 Google 文件。(這類作業通常稱為郵件合併)。

替換文字的方法有很多種，但最簡單的方法是使用下例所示的 replaceText() 方法。replaceText 支援 JavaScript 的大部分規則運算式功能。下方第一個函式會在 Google 文件中新增數行預留位置文字；在實際情況中，您比較可能會自行在文件中輸入預留位置。第二個函式會將預留位置替換為 client 物件中定義的屬性。

請注意，這兩個函式都會使用 getActiveDocument() 和 getActiveTab() 方法，而這兩個方法只適用於在 Google 文件中建立的指令碼；在獨立指令碼中，請改用 DocumentApp.create()、openById() 或 openByUrl() 搭配 Document.getTab()。

新增一些預留位置

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

替換預留位置

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);
}

自訂選單和使用者介面

您可以新增選單、對話方塊和側欄，自訂 Google 文件。不過請注意，指令碼只能與開啟文件的目前例項的 UI 互動，且只有在指令碼繫結至文件時才能如此。

瞭解如何在 Google 文件中新增自訂選單和對話方塊。如要進一步瞭解如何為對話方塊或側欄建立自訂介面，請參閱 HTML 服務指南。如果您打算將自訂介面發布為外掛程式的一部分，請遵循樣式指南，確保與 Google 文件編輯器的樣式和版面配置一致。

Google 文件外掛程式

外掛程式會在 Google 文件中執行，並可從 Google 文件外掛程式商店安裝。如果您已開發 Google 文件的腳本，並想與全世界分享，可以透過 Apps Script 發布腳本做為外掛程式，讓其他使用者從外掛程式商店安裝。

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

觸發條件

綁定 Google 文件的指令碼可使用簡單觸發事件回應文件的 onOpen 事件，這類事件會在使用者擁有文件的編輯權限，並在 Google 文件中開啟文件時發生。

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