扩展 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 文档的脚本可以使用简单触发器来响应该文档的 onOpen 事件,该事件只要拥有文档编辑权限的用户在 Google 文档中打开该文档,就会发生该事件。

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