扩展 Google 文档

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

基础知识

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

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

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

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

替换文字

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

您可以使用 replaceText 方法替换文字，该方法支持大多数 JavaScript 正则表达式 功能。在以下示例中，第一个函数向文档添加占位符文字，第二个函数将该文字替换为 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 文档。请注意，a 脚本只能与它所绑定的文档的界面互动。

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

Google 文档插件

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

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

触发器

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

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