扩展 Google 文档

借助 Google Apps 脚本,您可以以编程方式创建和修改 Google 文档,还可以通过新菜单、对话框和边栏自定义用户界面。

基础知识

Apps 脚本可以通过两种广泛的方式与 Google 文档互动:任何脚本都可以创建或修改文档(前提是脚本的用户拥有对该文档的相应权限),并且脚本还可以绑定到文档,这会赋予脚本更改用户界面或在文档打开时做出响应的特殊能力。如需在 Google 文档中创建容器绑定脚本,请依次点击扩展程序 > Apps 脚本

无论哪种情况,您都可以使用 Apps 脚本的 Document 服务与 Google 文档互动,如以下示例所示。

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

上述脚本会在用户的 Google 云端硬盘中创建一个新文档,然后检索 ID 为 t.0 的标签页(默认的第一个标签页),插入一个包含与文档名称相同的文本的段落,将该段落设置为标题样式,并附加一个基于二维数组中的值的表格。该脚本还可以通过将对 DocumentApp.create 的调用替换为 DocumentApp.openByIdopenByUrl,对现有文档进行这些更改。对于在文档内创建的脚本(容器绑定),请使用 DocumentApp.getActiveDocumentDocument.getActiveTab

文档的结构

从 Apps 脚本的角度来看,Google 文档的结构与 HTML 文档非常相似,也就是说,一个文档由一个或多个 Tab 对象组成,每个对象都包含元素(例如 ParagraphTable),这些元素通常包含其他元素。大多数用于修改 Google 文档的脚本都以调用 getTabasDocumentTab 开头,后跟 getBody,因为 Body 是一个核心元素,其中包含标签页中的所有其他元素,但 HeaderSectionFooterSection 和任何 Footnotes 除外。

不过,对于哪些类型的元素可以包含其他类型的元素,有一些规则。此外,Apps 脚本中的 Document 服务只能将某些类型的元素插入到其他元素中。以下树状图显示了哪些元素可以包含在特定类型的元素中。

以粗体显示的元素可以插入;非粗体元素只能就地操作。

替换文字

Apps 脚本通常用于替换 Google 文档中的文本。 假设您有一个包含大量客户信息的电子表格,并且您想为每位客户生成个性化的 Google 文档。(此类操作通常称为“邮件合并”。)

您可以使用 replaceText 方法替换文本,该方法支持大多数 JavaScript 正则表达式功能。在以下示例中,第一个函数向文档添加占位文本,第二个函数将该文本替换为 client 对象的属性。

这两个函数都使用 getActiveDocumentgetActiveTab 方法,这些方法仅适用于在 Google 文档中创建的脚本;在独立脚本中,请改用 DocumentApp.createopenByIdopenByUrl,并结合使用 Document.getTab

添加一些占位符

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

替换占位符

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

自定义菜单和界面

您可以通过添加自定义菜单对话框和边栏来自定义 Google 文档。请注意,脚本只能与它绑定到的文档的界面进行交互。

如需详细了解如何使用 HTML 和 CSS 创建自定义界面,请参阅 HTML 服务指南。 如果您打算将界面发布为插件,请遵循样式指南,确保其外观与 Google 文档编辑器保持一致。

Google 文档插件

插件在 Google 文档中运行,可从 Google 文档插件商店安装。如果您为 Google 文档开发了脚本,并希望与他人分享,那么 Apps 脚本可让您将脚本发布为插件,以便其他用户可以从插件商店安装该脚本。

如需创建 Google 文档插件,请参阅构建 Google 文档插件的快速入门指南

触发器

绑定到 Google 文档的脚本可以使用简单触发器来响应文档的 onOpen 事件,当有文档编辑权限的用户在 Google 文档中打开该文档时,就会发生此事件。

如需设置触发器,请编写一个名为 onOpen 的函数。如需查看此触发器的示例,请参阅 Google Workspace 中的自定义菜单。 虽然触发器可用于添加菜单,但它无法使用任何需要授权的 Apps 脚本服务。