此页面由 Cloud Translation API 翻译。

Class Document

一种包含富文本和元素（例如表格和列表）的文档。

您可以使用 DocumentApp 打开或创建文档。

// Open a document by ID.
var doc = DocumentApp.openById("<my-id>");

// Create and open a document.
doc = DocumentApp.create("Document Title");

方法

方法	返回类型	简介
`addBookmark(position)`	`Bookmark`	在给定的 `Position` 处添加一个 `Bookmark`。
`addEditor(emailAddress)`	`Document`	将指定用户添加到 `Document` 的编辑器列表中。
`addEditor(user)`	`Document`	将指定用户添加到 `Document` 的编辑器列表中。
`addEditors(emailAddresses)`	`Document`	将指定用户数组添加到 `Document` 的编辑器列表中。
`addFooter()`	`FooterSection`	添加文档页脚部分（如果不存在）。
`addHeader()`	`HeaderSection`	添加文档标头部分（如果不存在）。
`addNamedRange(name, range)`	`NamedRange`	添加了 `NamedRange`，后者是具有名称和 ID 以供日后检索的 `Range`。
`addViewer(emailAddress)`	`Document`	将指定用户添加到 `Document` 的查看者列表中。
`addViewer(user)`	`Document`	将指定用户添加到 `Document` 的查看者列表中。
`addViewers(emailAddresses)`	`Document`	将指定用户数组添加到 `Document` 的查看者列表中。
`getAs(contentType)`	`Blob`	将当前 `Document` 内容检索为指定类型的 blob。
`getBlob()`	`Blob`	将当前 `Document` 内容检索为 blob。
`getBody()`	`Body`	检索活跃文档的 `Body`。
`getBookmark(id)`	`Bookmark`	获取具有指定 ID 的 `Bookmark`。
`getBookmarks()`	`Bookmark[]`	获取文档中的所有 `Bookmark` 对象。
`getCursor()`	`Position`	获取活动文档中用户的光标。
`getEditors()`	`User[]`	获取此 `Document` 的编辑器列表。
`getFooter()`	`FooterSection`	检索文档的页脚部分（如果存在）。
`getFootnotes()`	`Footnote[]`	检索文档正文中的所有 `Footnote` 元素。
`getHeader()`	`HeaderSection`	检索文档的标头部分（如果存在）。
`getId()`	`String`	检索文档的唯一标识符。
`getLanguage()`	`String`	获取文档的语言代码。
`getName()`	`String`	用于检索文档的标题。
`getNamedRangeById(id)`	`NamedRange`	获取具有指定 ID 的 `NamedRange`。
`getNamedRanges()`	`NamedRange[]`	获取文档中的所有 `NamedRange` 对象。
`getNamedRanges(name)`	`NamedRange[]`	获取文档中具有指定名称的所有 `NamedRange` 对象。
`getSelection()`	`Range`	获取用户在活跃文档中所做的选择。
`getSupportedLanguageCodes()`	`String[]`	获取 Google 文档文件支持的所有语言代码。
`getUrl()`	`String`	检索用于访问当前文档的网址。
`getViewers()`	`User[]`	获取此 `Document` 的查看者和评论者列表。
`newPosition(element, offset)`	`Position`	创建一个新的 `Position`，它是相对于文档中特定位置的引用。
`newRange()`	`RangeBuilder`	创建一个构建器，用于根据文档元素构建 `Range` 对象。
`removeEditor(emailAddress)`	`Document`	从 `Document` 的编辑器列表中移除给定用户。
`removeEditor(user)`	`Document`	从 `Document` 的编辑器列表中移除给定用户。
`removeViewer(emailAddress)`	`Document`	将指定用户从 `Document` 的查看者和评论者列表中移除。
`removeViewer(user)`	`Document`	将指定用户从 `Document` 的查看者和评论者列表中移除。
`saveAndClose()`	`void`	保存当前的 `Document`。
`setCursor(position)`	`Document`	在给定 `Position` 的情况下，在活动文档中设置用户的光标。
`setLanguage(languageCode)`	`Document`	设置文档的语言代码。
`setName(name)`	`Document`	设置文档标题。
`setSelection(range)`	`Document`	根据 `Range`，设置用户在当前文档中所做的选择。

详细文档

`addBookmark(position)`

在给定的 Position 处添加一个 Bookmark。

参数

名称	类型	说明
`position`	`Position`	新书签的位置

Bookmark - 新书签

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addEditor(emailAddress)`

将指定用户添加到 Document 的编辑器列表中。如果用户已位于查看者列表中，则此方法会将该用户从查看者列表中升级。

参数

名称	类型	说明
`emailAddress`	`String`	要添加的用户的电子邮件地址。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addEditor(user)`

将指定用户添加到 Document 的编辑器列表中。如果用户已位于查看者列表中，则此方法会将该用户从查看者列表中升级。

参数

名称	类型	说明
`user`	`User`	要添加的用户的表示形式。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addEditors(emailAddresses)`

将指定用户数组添加到 Document 的编辑器列表中。如果其中有任何用户已经在查看者列表中，此方法会将他们从查看者列表中升级。

参数

名称	类型	说明
`emailAddresses`	`String[]`	要添加的用户的电子邮件地址数组。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addFooter()`

添加文档页脚部分（如果不存在）。

FooterSection - 文档页脚

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addHeader()`

添加文档标头部分（如果不存在）。

HeaderSection - 文档标头

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addNamedRange(name, range)`

添加了 NamedRange，后者是具有名称和 ID 以供日后检索的 Range。名称不一定是唯一的；同一文档中的多个不同范围可以同名，这与 HTML 中的类非常相似。相比之下，ID 在文档中是唯一的，就像 HTML 中的 ID 一样。向文档添加 NamedRange 后，您无法对文档进行修改，只能将其移除。

任何访问文档的脚本都可以访问 NamedRange。为避免脚本之间发生意外冲突，不妨考虑使用唯一字符串作为范围名称的前缀。

// Creates a named range that includes every table in the document.
var doc = DocumentApp.getActiveDocument();
var rangeBuilder = doc.newRange();
var tables = doc.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.addNamedRange('Document tables', rangeBuilder.build());

参数

名称	类型	说明
`name`	`String`	范围的名称，不必具有唯一性；范围名称必须介于 1 到 256 个字符之间。
`range`	`Range`	要与名称关联的元素范围；范围可以是主动选择、搜索结果，也可以使用 `newRange()` 手动构建。

NamedRange - NamedRange。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addViewer(emailAddress)`

将指定用户添加到 Document 的查看者列表中。如果用户已经在编辑器列表中，则此方法不会产生任何影响。

参数

名称	类型	说明
`emailAddress`	`String`	要添加的用户的电子邮件地址。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addViewer(user)`

将指定用户添加到 Document 的查看者列表中。如果用户已经在编辑器列表中，则此方法不会产生任何影响。

参数

名称	类型	说明
`user`	`User`	要添加的用户的表示形式。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`addViewers(emailAddresses)`

将指定用户数组添加到 Document 的查看者列表中。如果任何用户已经在编辑器列表中，此方法对他们没有影响。

参数

名称	类型	说明
`emailAddresses`	`String[]`	要添加的用户的电子邮件地址数组。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getAs(contentType)`

将当前 Document 内容检索为指定类型的 blob。

参数

名称	类型	说明
`contentType`	`String`	要转换为的 MIME 类型；目前仅支持 `'application/pdf'`

Blob - 当前文档作为 blob

`getBlob()`

将当前 Document 内容检索为 blob。

Blob - 当前文档作为 blob

`getBody()`

检索活跃文档的 Body。

文档可能包含不同类型的部分（例如 HeaderSection 和 FooterSection）。文档的有效部分是 Body。

Document 中的元素方法可委托给活跃的 Body。

Body - 活跃文档正文部分

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getBookmark(id)`

获取具有指定 ID 的 Bookmark。如果不存在此类 Bookmark，此方法会返回 null。

参数

名称	类型	说明
`id`	`String`	`Bookmark`的 ID

Bookmark - 具有指定 ID 的 Bookmark；如果不存在此类 Bookmark，则为 null

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getBookmarks()`

获取文档中的所有 Bookmark 对象。

Bookmark[] - 文档中 Bookmark 对象的数组

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getCursor()`

获取活动文档中用户的光标。脚本只能访问正在运行脚本的用户的光标，并且仅当将该脚本绑定到文档时才有权限。

// Insert some text at the cursor position and make it bold.
var cursor = DocumentApp.getActiveDocument().getCursor();
if (cursor) {
  // Attempt to insert text at the cursor position. If the insertion returns null, the cursor's
  // containing element doesn't allow insertions, so show the user an error message.
  var element = cursor.insertText('ಠ‿ಠ');
  if (element) {
    element.setBold(true);
  } else {
    DocumentApp.getUi().alert('Cannot insert text here.');
  }
} else {
  DocumentApp.getUi().alert('Cannot find a cursor.');
}

Position - 用户光标的表示形式，如果用户没有在文档中放置光标，或者脚本未绑定到文档，则为 null。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getEditors()`

获取此 Document 的编辑器列表。

User[] - 具有修改权限的用户数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getFooter()`

检索文档的页脚部分（如果存在）。

FooterSection - 文档页脚

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getFootnotes()`

检索文档正文中的所有 Footnote 元素。

调用 getFootnotes 会导致遍历文档元素。对于大型文档，请避免对此方法进行不必要的调用。

Footnote[] - 文档脚注

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getHeader()`

检索文档的标头部分（如果存在）。

HeaderSection - 文档标头

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getId()`

检索文档的唯一标识符。将文档 ID 与 DocumentApp.openById() 配合使用以打开特定的文档实例。

String - 文档的 ID

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getLanguage()`

获取文档的语言代码。这是文档编辑器的文件 > 语言中显示的语言，这可能不是文档的实际语言。

String - 文档语言，如果未定义，则设为 null。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getName()`

用于检索文档的标题。

String - 文档标题

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getNamedRangeById(id)`

获取具有指定 ID 的 NamedRange。如果不存在此类 NamedRange，此方法会返回 null。名称不一定是唯一的；同一文档中的多个不同范围可以同名，这与 HTML 中的类非常相似。相比之下，ID 在文档中是唯一的，就像 HTML 中的 ID 一样。

参数

名称	类型	说明
`id`	`String`	范围的 ID，在文档中具有唯一性

NamedRange - 具有指定 ID 的 NamedRange；如果不存在此类范围，则为 null

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getNamedRanges()`

获取文档中的所有 NamedRange 对象。

NamedRange 可供访问文档的任何脚本访问。为避免脚本之间发生意外冲突，不妨考虑使用唯一字符串作为范围名称的前缀。

NamedRange[] - 文档中 NamedRange 对象的数组，可能包含多个同名范围

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getNamedRanges(name)`

获取文档中具有指定名称的所有 NamedRange 对象。名称不必是唯一的；同一文档中的多个不同范围可以使用相同的名称，很像 HTML 中的类。相比之下，ID 在文档中是唯一的，就像 HTML 中的 ID 一样。

NamedRange 可供访问文档的任何脚本访问。为避免脚本之间发生意外冲突，不妨考虑使用唯一字符串作为范围名称的前缀。

参数

名称	类型	说明
`name`	`String`	范围的名称，该名称不必是唯一的

NamedRange[] - 文档中具有指定名称的 NamedRange 对象的数组

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getSelection()`

获取用户在活跃文档中所做的选择。脚本只能访问正在运行该脚本的用户，并且该脚本必须绑定到文档。

// Display a dialog box that tells the user how many elements are included in the selection.
var selection = DocumentApp.getActiveDocument().getSelection();
if (selection) {
  var elements = selection.getRangeElements();
  DocumentApp.getUi().alert('Number of selected elements: ' + elements.length);
} else {
  DocumentApp.getUi().alert('Nothing is selected.');
}

Range - 表示用户所选择的内容；如果用户未在文档中选择任何内容，则选择 null；如果仅选择段落结尾、仅选择段落结尾和新行，或者脚本未绑定到文档。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getSupportedLanguageCodes()`

获取 Google 文档文件支持的所有语言代码。

String[] - 语言代码数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getUrl()`

检索用于访问当前文档的网址。

var doc = DocumentApp.getActiveDocument();

// Send out the link to open the document.
MailApp.sendEmail("<email-address>", doc.getName(), doc.getUrl());

String - 用于访问当前文档的网址

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`getViewers()`

获取此 Document 的查看者和评论者列表。

User[] - 拥有查看或评论权限的用户数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`newPosition(element, offset)`

创建一个新的 Position，它是相对于文档中特定位置的引用。用户的光标以 Position 以及其他多种用法表示。

// Append a paragraph, then place the user's cursor after the first word of the new paragraph.
var doc = DocumentApp.getActiveDocument();
var paragraph = doc.getBody().appendParagraph('My new paragraph.');
var position = doc.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

参数

名称	类型	说明
`element`	`Element`	包含新 `Position` 的元素；这必须是 `Text` 元素或 `Paragraph` 之类的容器元素
`offset`	`Integer`	对于 `Text` 元素，它是 `Position` 之前的字符数量；对于其他元素，是同一容器元素中 `Position` 之前的子元素的数量

Position - 新的 Position

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`newRange()`

创建一个构建器，用于根据文档元素构建 Range 对象。

// Change the user's selection to a range that includes every table in the document.
var doc = DocumentApp.getActiveDocument();
var rangeBuilder = doc.newRange();
var tables = doc.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

RangeBuilder - 新构建器

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`removeEditor(emailAddress)`

从 Document 的编辑器列表中移除给定用户。如果用户属于具有常规访问权限的一类用户（例如，与用户的整个网域共享 Document，或用户可访问的 Document 位于共享云端硬盘中），则此方法不会阻止用户访问 Document。

对于云端硬盘文件，此操作还会将用户从查看者列表中移除。

参数

名称	类型	说明
`emailAddress`	`String`	要移除的用户的电子邮件地址。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`removeEditor(user)`

对于云端硬盘文件，此操作还会将用户从查看者列表中移除。

参数

名称	类型	说明
`user`	`User`	要移除的用户的表示形式。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`removeViewer(emailAddress)`

将指定用户从 Document 的查看者和评论者列表中移除。如果用户是编辑者，而不是查看者或评论者，则此方法不会产生任何影响。如果用户所属的类别具有常规访问权限（例如，如果与用户的整个网域共享了 Document，或者 Document 位于用户可以访问的共享云端硬盘中），则此方法也不会阻止用户访问 Document。

对于云端硬盘文件，此操作还会将用户从编辑者列表中移除。

参数

名称	类型	说明
`emailAddress`	`String`	要移除的用户的电子邮件地址。

Document - 用于串联的 Document。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`removeViewer(user)`

将指定用户从 Document 的查看者和评论者列表中移除。如果用户是编辑者，而非查看者，则此方法无效。如果用户所属的类别具有常规访问权限（例如，如果与用户的整个网域共享了 Document，或者 Document 位于用户可以访问的共享云端硬盘中），则此方法也不会阻止用户访问 Document。

对于云端硬盘文件，此操作还会将用户从编辑者列表中移除。

参数

名称	类型	说明
`user`	`User`	要移除的用户的表示形式。

Document - 用于串联的 Document。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`saveAndClose()`

保存当前的 Document。会导致系统刷新并应用待处理的更新。

在每次打开的可修改 Document 的脚本执行结束时，系统会自动调用 saveAndClose() 方法。

已停业的Document无法修改。使用 DocumentApp.openById() 重新打开给定文档进行修改。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`setCursor(position)`

在给定 Position 的情况下，在活动文档中设置用户的光标。脚本只能访问正在运行脚本的用户的光标，并且仅当将该脚本绑定到文档时才有权限。

// Append a paragraph, then place the user's cursor after the first word of the new paragraph.
var doc = DocumentApp.getActiveDocument();
var paragraph = doc.getBody().appendParagraph('My new paragraph.');
var position = doc.newPosition(paragraph.getChild(0), 2);
doc.setCursor(position);

参数

名称	类型	说明
`position`	`Position`	新的光标位置

Document - 此 Document，用于连锁

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`setLanguage(languageCode)`

设置文档的语言代码。这是文档编辑器的文件 > 语言中显示的语言，这可能不是文档的实际语言。使用 getSupportedLanguageCodes() 可获取所有有效的语言代码。

参数

名称	类型	说明
`languageCode`	`String`	语言代码。

Document - 此 Document，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`setName(name)`

设置文档标题。

参数

名称	类型	说明
`name`	`String`	新文档标题

Document - 当前文档

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents

`setSelection(range)`

根据 Range，设置用户在当前文档中所做的选择。脚本只能访问正在运行该脚本的用户，并且该脚本必须绑定到文档。

// Change the user's selection to a range that includes every table in the document.
var doc = DocumentApp.getActiveDocument();
var rangeBuilder = doc.newRange();
var tables = doc.getBody().getTables();
for (var i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());

参数

名称	类型	说明
`range`	`Range`	新选择的元素范围

Document - 此 Document，用于连锁

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

https://www.googleapis.com/auth/documents.currentonly
https://www.googleapis.com/auth/documents