擴充 Google 文件

Google Apps Script 能讓您以程式輔助的方式建立及修改 Google 文件 新增選單、對話方塊和自訂使用者介面 側欄

基本概念

Apps Script 與 Google 文件互動的方式有兩種:任何指令碼都能 建立或修改文件,前提是該指令碼使用者俱備適當的權限 或指令碼也可以 繫結至文件, 指令碼的特殊功能,可以修改使用者介面或 文件已開啟。如要在 Google 文件中建立容器繫結指令碼,請按照下列步驟操作: 依序點選「擴充功能」>「Apps Script」

不論是哪一種情況,都可以透過以下方式輕鬆與 Google 文件互動 Apps Script 文件服務,如以下範例所示 示範。

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 文件的結構 也就是 文件 包含一或多個 Tab 物件,每個物件都包含 元素 (例如 ParagraphTable),通常包含其他 元素。大多數修改 Google 文件的指令碼開頭都是呼叫 getTab()asDocumentTab() 後面接著 getBody(), 因為 Body 是核心元素 這類元素包含分頁上的所有其他元素,但 HeaderSection, FooterSection和任何 Footnotes

不過,其他元素類型可以包含其他類型的相關規則。 此外,Apps Script 中的「文件服務」只能插入 將特定類型的元素組合到其他元素中下面樹狀圖顯示 元素可以包含在特定類型的元素中。

可插入以粗體顯示的元素;非粗體元素 受到操弄

取代文字

Apps Script 常用於取代 Google 文件中的文字。假設您有 製作出內含客戶資訊的試算表 Google 文件。(這類作業通常稱為郵件 merge.)

取代文字的方法有很多種,最簡單的方式是 replaceText() 方法,如以下範例所示。replaceText 支援大多數 讓您瞭解各種程式碼工具的規則運算式功能下列第一個函式 在 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 文件對話方塊。 如要進一步瞭解如何為對話方塊或側欄建立自訂介面,請參閱 HTML 服務指南。 如果您計劃將自訂介面 外掛程式,然後按照 符合樣式指南,確保與 以及 Google 文件編輯器的樣式和版面配置

Google 文件外掛程式

外掛程式會在 Google 文件中執行,且可安裝 開啟「Google 文件」外掛程式商店如果您已為 Google 文件開發指令碼 想要與全世界的人分享 使用 Apps Script 時 將指令碼發布為 外掛程式,其他使用者就能從外掛程式商店安裝。

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

觸發條件

繫結至 Google 的指令碼 Google 文件可使用簡易觸發條件回應 加入文件的 onOpen 事件, 每當擁有文件編輯權限的使用者在 Google 文件中開啟文件時,就會發生此情況。

如要設定觸發條件,只要編寫名為 onOpen() 的函式即可。範例說明 請參閱 Google Workspace 的自訂選單。 雖然這項簡易觸發條件對於新增選單很有用,但無法用於新增任何應用程式 需要授權的指令碼服務。