扩展 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 文档由通常包含其他元素的元素(如 ParagraphTable)组成。修改 Google 文档的大多数脚本都以对 getBody() 的调用开头,因为 Body 是一个主元素,包含除 HeaderSectionFooterSection 和任何 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 脚本允许您将脚本作为插件publish,以便其他用户从插件商店安装该脚本。

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

触发器

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

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