內建 Google 服務

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.71.8 的部分功能。選擇要搭配指令碼使用的執行階段,但強烈建議使用 V8 執行階段。

除了內建和進階 Google 服務,每個執行階段都支援 JavaScript 類別和物件,供指令碼使用。您的指令碼可以使用 ArrayDateRegExp等等常見物件,以及 MathObject 全域物件。

由於 Apps Script 程式碼是在 Google 的伺服器上執行 (HTML 服務網頁除外),因此 Apps Script 無法使用瀏覽器 JavaScript 功能,例如 DOM 操控或 Window API。

自動完成

指令碼編輯器提供「內容輔助」功能 (一般稱為「自動完成」),可顯示全域物件,以及在指令碼目前情境中有效的函式和列舉。每當您在全域物件、列舉或方法呼叫後輸入半形句號,系統就會自動顯示自動完成建議,這些呼叫會傳回 Apps Script 類別。例如:

  • 如果您輸入全域物件的完整名稱,或從自動完成功能選取一個名稱,然後輸入 . (半形句號),系統就會顯示該類別的所有方法和列舉。
  • 輸入幾個字元後,系統會顯示以這些字元開頭的所有有效建議。

全域物件

每項服務至少會提供一個全域 (頂層) 物件;舉例來說,Gmail 服務只能透過 GmailApp 物件存取。部分服務提供多個全域物件,例如「基礎服務」包含四個全域物件:BrowserLoggerMimeTypeSession

方法

幾乎所有內建或進階服務的全域物件都包含傳回資料或 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 介面代表其他類別,可能是 ParagraphTable。介面物件本身很少有用,請改為呼叫 Element.asParagraph() 等方法,將物件轉換回特定類別。

列舉

大多數服務都包含具名值的列舉 (列舉型別)。舉例來說,Google 雲端硬碟服務會使用列舉 AccessPermission,判斷哪些使用者有權存取檔案或資料夾。在大多數情況下,您會從全域物件存取這些列舉,如以下範例所示:

// 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);