擴充 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 的 Document Service 只能將特定類型的元素插入其他元素。下方的樹狀結構顯示特定類型的元素可包含哪些元素。

以粗體顯示的元素可以插入，非粗體顯示的元素只能在原位置操作。

取代文字

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 服務。