Google Apps Script 提供超過 30 種內建服務,能夠與使用者資料、其他 Google 系統和外部系統互動。這些服務以全域物件的形式提供,遵循 JavaScript 標準 Math
物件。舉例來說,就像 Math
提供方法 (例如 random()
) 和常數 (例如 PI
) 一樣,Apps Script 的試算表服務也提供 openById(id)
等方法、Range
等類別和 DataValidationCriteria
等列舉。
控制 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
物件存取。部分服務提供多個全域物件,例如,基礎服務包含四個全域物件: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.getBody();
body.appendParagraph('New paragraph.');
// Same result as above.
DocumentApp.create('New document').getBody().appendParagraph('New paragraph.');
存取子項類別
每個服務都包含一或多個子項類別,這些頂層類別無法以全域物件的形式存取。您不能使用 new
關鍵字建構這些類別,就像使用 Date
等標準 JavaScript 類別一樣;您只能呼叫傳回該類別的方法,才能存取子項類別。如果不確定如何存取特定類別,請造訪該服務的參考說明文件,並尋找會傳回所需類別的方法。
處理介面
少數服務包括特殊參考文件,在參考說明文件中標示為「介面」的特殊類別。這些是一般類別,做為無法事先判斷精確方法的方法傳回類型;舉例來說,Document Service 方法 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);