Google Apps Script 提供 30 多項內建服務,可與使用者資料、其他 Google 系統和外部系統互動。這些服務會以全域物件的形式提供,類似於 JavaScript 的標準 Math
物件。舉例來說,就像 Math
提供 random()
等方法和 PI
等常數,Apps Script 的試算表服務也提供 openById(id)
等方法、Range
等類別 (子項物件),以及 DataValidationCriteria
等列舉。
控制Google Workspace 產品的服務參考文件收錄於本網站側欄「參考資料」標題下方的「Google Workspace 服務」部分。公用服務 (用於建立使用者介面、剖析 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 類別的全域物件、枚舉或方法呼叫後輸入一個句點,系統就會自動顯示自動完成建議。例如:
- 如果您輸入全域物件的完整名稱,或從自動完成功能中選取一個全域物件,然後輸入
.
(一個句點),您就會看到該類別的所有方法和列舉。 - 只要輸入幾個字元,系統就會顯示所有以這些字元開頭的有效建議。
瞭解全域物件
每項服務至少會提供一個全域 (頂層) 物件;舉例來說,Gmail 服務只能透過 GmailApp
物件存取。部分服務會提供多個全域物件,例如Base 服務包含四個全域物件: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 指令程式類別,您可以在一行中連結方法呼叫。(傳回類型會顯示在自動完成功能和方法參照文件中)。舉例來說,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 類別;您只能透過呼叫會傳回子類別的方法存取子類別。如果不確定如何存取特定類別,請前往服務參考說明文件的根目錄頁面,尋找可傳回所需類別的方法。
處理介面
少數服務包含在參考說明文件中標示為「介面」的特殊類別。這些泛型類別可用於無法預先判斷確切類型的方法,做為傳回類型;例如,文件服務方法 Body.getChild(childIndex)
會傳回泛型 Element
物件。Element
是代表其他類別的介面,可能是 Paragraph
或 Table
。介面物件很少單獨使用,您通常會呼叫 Element.asParagraph()
這類方法,將物件轉換回精確的類別。
使用列舉
大多數服務都包含幾個具名值的列舉 (列舉型別)。舉例來說,雲端硬碟服務會使用 Access
和 Permission
列舉,判斷哪些使用者可存取檔案或資料夾。在大多數情況下,您會從全域物件存取這些列舉。舉例來說,呼叫 Folder.setSharing(accessType, permissionType)
方法的情況如下所示:
// 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);