扩展 Google 文档

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

基础知识

Apps Script 可以通过两种主要方式与 Google 文档互动：如果脚本的用户对文档拥有适当的权限，则任何脚本都可以创建或修改文档；脚本还可以绑定到文档，这会赋予脚本特殊能力，使其能够更改界面或在文档打开时做出响应。如需在 Google 文档中创建容器绑定脚本，请依次点击扩展 > Apps 脚本。

无论是哪种情况，您都可以通过 Google Apps 脚本的文档服务轻松与 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 Script 的角度来看，Google 文档的结构与 HTML 文档非常相似，也就是说，文档由一个或多个 Tab 对象组成，每个对象都包含通常包含其他元素的元素（例如 Paragraph 或 Table）。大多数用于修改 Google 文档的脚本都以调用 getTab() 和 asDocumentTab() 开头，然后是 getBody()，因为 Body 是一个核心元素，包含标签页中的所有其他元素（HeaderSection、FooterSection 和任何 Footnotes 除外）。

不过，对于哪些类型的元素可以包含其他类型，是有规则的。此外，Apps Script 中的文档服务只能将某些类型的元素插入其他元素。下图显示了某种类型的元素可以包含哪些元素。

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

替换文本

Apps Script 通常用于替换 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 Script 将脚本发布为插件，以便其他用户从插件商店中安装该脚本。

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

触发器

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

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