擴充 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 文件是由許多元素 (例如 ParagraphTable) 組成,這些元素通常包含其他元素。大多數修改 Google 文件的指令碼都會從呼叫 getBody() 開始,因為 Body 是包含所有其他元素的主要元素,但 HeaderSectionFooterSection 和任何 Footnotes 除外。

不過,某些元素類型可包含其他類型的規則。此外,Apps Script 中的 Document 服務只能插入特定類型的元素。下圖顯示特定類型元素可以包含的元素。

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

取代文字

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 文件。請注意,指令碼只能與已開啟文件目前執行個體的 UI 互動,且只有在指令碼繫結至文件時。

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

Google 文件外掛程式

外掛程式會在 Google 文件中執行,且可從 Google 文件外掛程式商店安裝。如果您已開發 Google 文件指令碼,並且想要與全世界分享,Apps Script 可讓您以外掛程式的形式publish指令碼,讓其他使用者能夠從外掛程式商店安裝該指令碼。

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

觸發條件

已「繫結」至 Google 文件的指令碼可以使用簡易觸發條件來回應文件的 onOpen 事件,且每當具備文件編輯權限的使用者在 Google 文件開啟文件時,就會發生這個事件。

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