扩展 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.openById() 或 openByUrl()，脚本就可以轻松地对现有文档进行这些更改。对于在文档内创建的脚本（容器绑定），请使用 DocumentApp.getActiveDocument() 和 Document.getActiveTab()。

文档的结构

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

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

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

替换文字

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

您可以通过多种方式替换文本，但最简单的方式是使用 replaceText() 方法，如下例所示。replaceText 支持 JavaScript 的大多数正则表达式功能。下面的第一个函数会向 Google 文档添加几行占位文本；在实际应用中，您更可能会自行在文档中输入占位文本。第二个函数会将占位符替换为 client 对象中定义的属性。

请注意，这两个函数都使用 getActiveDocument() 和 getActiveTab() 方法，这些方法仅适用于在 Google 文档中创建的脚本；在独立脚本中，请改用 DocumentApp.create()、openById() 或 openByUrl()，并与 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 文档。不过请注意，脚本只能与打开的文档的当前实例的界面互动，并且只有当脚本绑定到文档时才能互动。

了解如何向 Google 文档添加自定义菜单和对话框。 如需详细了解如何为对话框或边栏创建自定义界面，请参阅 HTML 服务指南。 如果您打算将自定义界面作为插件的一部分发布，请遵循样式指南，以确保与 Google 文档编辑器的样式和布局保持一致。

Google 文档插件

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

如需了解如何为 Google 文档创建插件，请参阅构建 Google 文档插件的快速入门。

触发器

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

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