Google Apps Script 提供超過 30 項內建服務,可與使用者資料、其他 Google 系統和外部系統互動。這些服務會以全域物件的形式提供,類似於 JavaScript 的標準 Math 物件。舉例來說,就像 Math 提供 random() 等方法和 PI 等常數一樣,Apps Script 的 Spreadsheet 服務提供 openById(id) 等方法、Range 等類別 (子物件) 和 DataValidationCriteria 等列舉。
控制 Google Workspace 產品的服務參考文件,會收集在這個網站側欄「Reference」標題下方的「Google Workspace Services」部分。實用程式服務 (例如建立使用者介面、剖析 XML 或寫入記錄資料) 會收集在「指令碼服務」部分。
現代 JavaScript 功能
Apps Script 支援兩種 JavaScript 執行階段:新版 V8 執行階段,以及由 Mozilla 的 Rhino JavaScript 解譯器支援的舊版執行階段。
V8 執行階段支援新版 ECMAScript 語法和功能。Rhino 執行階段是以較舊的 JavaScript 1.6 標準為基礎,並加上 1.7 和 1.8 的部分功能。選擇要搭配指令碼使用的執行階段,但強烈建議使用 V8 執行階段。
除了內建和進階 Google 服務,每個執行階段都支援 JavaScript 類別和物件,供指令碼使用。您的指令碼可以使用 Array、Date、RegExp、等等常見物件,以及 Math 和 Object 全域物件。
由於 Apps Script 程式碼是在 Google 的伺服器上執行 (HTML 服務網頁除外),因此 Apps Script 無法使用瀏覽器 JavaScript 功能,例如 DOM 操控或 Window API。
自動完成
指令碼編輯器提供「內容輔助」功能 (一般稱為「自動完成」),可顯示全域物件,以及在指令碼目前情境中有效的函式和列舉。每當您在全域物件、列舉或方法呼叫後輸入半形句號,系統就會自動顯示自動完成建議,這些呼叫會傳回 Apps Script 類別。例如:
- 如果您輸入全域物件的完整名稱,或從自動完成功能選取一個名稱,然後輸入
.(半形句號),系統就會顯示該類別的所有方法和列舉。 - 輸入幾個字元後,系統會顯示以這些字元開頭的所有有效建議。
全域物件
每項服務至少會提供一個全域 (頂層) 物件;舉例來說,Gmail 服務只能透過 GmailApp 物件存取。部分服務提供多個全域物件,例如「基礎服務」包含四個全域物件:Browser、Logger、MimeType 和 Session。
方法
幾乎所有內建或進階服務的全域物件都包含傳回資料或 Apps Script 類別的方法。指令碼會以這種格式呼叫方法:
GlobalObjectName.methodName(argument1, argument2, ..., argumentN);
舉例來說,指令碼可以呼叫 Gmail 服務的 sendEmail(recipient, subject, body) 方法來傳送電子郵件,如下所示:
GmailApp.sendEmail('claire@example.com', 'Subject line', 'This is the body.');
如果方法會傳回其他 Apps Script 類別,請在一行中鏈結方法呼叫。(自動完成功能和方法參考文件中都會顯示傳回型別)。舉例來說,方法 DocumentApp.create() 會傳回 Document,因此下列兩段程式碼的效果相同:
var doc = DocumentApp.create('New document');
var body = doc.getTab('t.0').asDocumentTab().getBody();
body.appendParagraph('New paragraph.');
// Same result as above.
DocumentApp.create('New document').getTab('t.0').asDocumentTab().getBody()
.appendParagraph('New paragraph.');
兒童課程
每項服務都包含一或多個子項類別,您無法從頂層以全域物件的形式存取這些類別。您也無法使用 new 關鍵字建構這些類別,就像使用 Date 等標準 JavaScript 類別一樣。如要存取子類別,您必須呼叫會傳回子類別的方法。如果不確定如何存取特定類別,請前往服務的參考說明文件根頁面,其中列出服務的類別,以及傳回這些類別的方法。
介面
部分服務會在參考文件將類別標示為「介面」。這些是泛型類別,用做無法預先判斷確切類型的方法傳回型別。舉例來說,Document 服務方法 Body.getChild(childIndex) 會傳回一般 Element 物件。Element 介面代表其他類別,可能是 Paragraph 或 Table。介面物件本身很少有用,請改為呼叫 Element.asParagraph() 等方法,將物件轉換回特定類別。
列舉
大多數服務都包含具名值的列舉 (列舉型別)。舉例來說,Google 雲端硬碟服務會使用列舉 Access 和 Permission,判斷哪些使用者有權存取檔案或資料夾。在大多數情況下,您會從全域物件存取這些列舉,如以下範例所示:
// Creates a folder that anyone on the Internet can read from and write to.
// (Domain administrators can prohibit this setting for Google Workspace users.)
var folder = DriveApp.createFolder('Shared Folder');
folder.setSharing(DriveApp.Access.ANYONE, DriveApp.Permission.EDIT);