Google Apps 脚本提供了 30 多项内置服务,可用于与用户数据、其他 Google 系统和外部系统进行交互。这些服务以类似于 JavaScript 标准 Math 对象的全局对象形式提供。例如,正如 Math 提供 random() 等方法和 PI 等常量一样,Apps 脚本的电子表格服务提供 openById(id) 等方法、Range 等类(子对象)和 DataValidationCriteria 等枚举。
用于控制 Google Workspace 产品的服务的参考文档收集在本网站边栏中“参考”标题下的“Google Workspace 服务”部分。实用程序服务(用于创建界面、解析 XML 或写入日志数据等)收集在“脚本服务”部分中。
现代 JavaScript 功能
Apps 脚本支持两种 JavaScript 运行时:由 Mozilla 的 Rhino JavaScript 解释器提供支持的旧版运行时和新版 V8 运行时。
V8 运行时支持现代 ECMAScript 语法和功能。Rhino 运行时基于较旧的 JavaScript 1.6 标准,外加 1.7 和 1.8 中的一些功能。选择要与脚本搭配使用的运行时,但强烈建议使用 V8 运行时。
除了内置服务和高级 Google 服务之外,每个运行时还支持可供脚本使用的 JavaScript 类和对象。脚本可以使用 Array、Date、RegExp 等常见对象,还可以使用 Math 和 Object 全局对象。
由于 Apps 脚本代码在 Google 的服务器上运行(HTML 服务页面除外),因此基于浏览器的 JavaScript 功能(例如 DOM 操作或 Window API)在 Apps 脚本中不可用。
自动补全
脚本编辑器提供“内容辅助”功能(更常称为“自动补全”),该功能可显示在脚本的当前上下文中有效的全局对象以及方法和枚举。每当您在返回 Apps 脚本类的全局对象、枚举或方法调用后输入句点时,系统都会自动显示自动补全建议。例如:
- 如果您输入全局对象的完整名称或从自动补全功能中选择一个,然后输入
.(句点),您会看到该类的所有方法和枚举。 - 如果您输入几个字符,系统会显示以这些字符开头的所有有效建议。
全局对象
每项服务至少提供一个全局(顶级)对象;例如,Gmail 服务只能通过 GmailApp 对象访问。某些服务提供多个全局对象;例如,基本服务包含四个全局对象:Browser、Logger、MimeType 和 Session。
方法
几乎所有内置服务或高级服务的全局对象都包含返回数据或 Apps 脚本类的方法。脚本按以下格式进行方法调用:
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.');
子类
每个服务都包含一个或多个子类,您无法从顶层以全局对象的形式访问这些子类。您也无法像使用标准 JavaScript 类(例如 Date)那样使用 new 关键字来构造这些类。如需访问子类,您必须调用返回该子类的方法。如果您不确定如何访问某个类,请访问该服务的参考文档的根网页,其中列出了该服务的类以及返回这些类的方法。
接口
某些服务包含在参考文档中标记为“接口”的类。这些是泛型类,用作无法预先确定精确类型的方法的返回类型。例如,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);