扩展 Google 文档

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

基础知识

Apps 脚本可以通过以下两种方式与 Google 文档交互：使用任何脚本，只要用户对文档拥有相应权限，任何脚本都可以创建或修改；脚本还可以绑定到文档，这让脚本具有特殊功能，可以在文档打开时更改界面或响应。如需在 Google 文档中创建容器绑定脚本，请点击扩展程序 > Apps 脚本。

无论是哪种情况，都可以通过 Apps 脚本的文档服务与 Google 文档轻松互动，如以下示例所示。

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.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 云端硬盘中创建一个新文档，然后插入一个段落，其中包含与文档名称相同的文本，将该段落的样式设为标题，并根据二维数组中的值附加表格。通过将对 DocumentApp.create() 的调用替换为 DocumentApp.openById() 或 openByUrl()，脚本可以轻松对现有文档进行这些更改。对于在文档内创建的脚本（容器绑定），请使用 DocumentApp.getActiveDocument()。

文档的结构

从 Apps 脚本的角度来看，Google 文档的结构类似于 HTML 文档，也就是说，Google 文档由通常包含其他元素的元素（例如 Paragraph 或 Table）组成。修改 Google 文档的大多数脚本都会调用 getBody()，因为 Body 是主元素，其中包含除 HeaderSection、FooterSection 和任何 Footnotes 以外的所有其他元素。

不过，需遵守一些规则，规定哪些类型的元素可以包含其他类型的元素。此外，Apps 脚本中的文档服务只能插入特定类型的元素。下面的树显示了特定类型的元素可以包含哪些元素。

可以插入以粗体显示的元素；非粗体元素只能在适当位置进行操作。

正在替换文本

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

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

请注意，这两个函数均使用 getActiveDocument() 方法，该方法仅适用于在 Google 文档内创建的脚本；在独立脚本中，请改用 DocumentApp.create()、openById() 或 openByUrl()。

添加一些占位符

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

替换占位符

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .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 文档的脚本可以使用简单触发器来响应该文档的 onOpen 事件，只要拥有文档编辑权限的用户在 Google 文档中打开该文档，就会发生该事件。

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