此页面由 Cloud Translation API 翻译。

Class Document

一个文档，包含一个或多个 Tab 对象，每个对象都包含富文本和元素（例如表格和列表）。

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

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

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

Document 类中直接访问和修改文本内容的方法会在活动标签页（在绑定到特定文档的脚本中）或第一个标签页（如果没有活动标签页）上运行。依赖于这些方法（例如 getBody()）的脚本可以迁移为使用 getTabs() 和 Tab.asDocumentTab() 来支持标签页。

方法

方法	返回类型	简介
`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`，可用于稍后检索；对于绑定到文档的脚本，则在活动标签页中添加 `NamedRange`。
`addViewer(emailAddress)`	`Document`	将指定用户添加到 `Document` 的观看者列表中。
`addViewer(user)`	`Document`	将指定用户添加到 `Document` 的观看者列表中。
`addViewers(emailAddresses)`	`Document`	将指定的用户数组添加到 `Document` 的观看者列表中。
`getActiveTab()`	`Tab`	获取文档中用户当前有效的 `Tab`。
`getAs(contentType)`	`Blob`	以指定类型的 blob 形式检索当前 `Document` 内容。
`getBlob()`	`Blob`	以 blob 形式检索当前 `Document` 内容。
`getBody()`	`Body`	检索第一个标签页的 `Body`；对于绑定到文档的脚本，则检索活动标签页的 `DocumentBodySection`。
`getBookmark(id)`	`Bookmark\|null`	获取第一个标签页中具有指定 ID 的 `Bookmark`，或者，对于绑定到文档的脚本，获取活动标签页中具有指定 ID 的 `Bookmark`。
`getBookmarks()`	`Bookmark[]`	获取第一个标签页中的所有 `Bookmark` 对象，或者对于绑定到文档的脚本，获取活动标签页中的所有 `Bookmark` 对象。
`getCursor()`	`Position\|null`	获取活跃标签页中的用户光标。
`getEditors()`	`User[]`	获取相应 `Document` 的编辑者列表。
`getFooter()`	`FooterSection\|null`	检索第一个标签页的页脚部分，或者，对于绑定到文档的脚本，检索活动标签页的页脚部分。
`getFootnotes()`	`Footnote[]\|null`	检索第一个标签页正文中的所有 `Footnote` 元素；对于绑定到文档的脚本，则检索活动标签页正文中的所有 `Footnote` 元素。
`getHeader()`	`HeaderSection\|null`	检索第一个标签页的标题部分；对于绑定到文档的脚本，则检索活动标签页的标题部分。
`getId()`	`String`	检索文档的唯一标识符。
`getLanguage()`	`String`	获取文档的语言代码。
`getName()`	`String`	检索文档的标题。
`getNamedRangeById(id)`	`NamedRange\|null`	获取第一个标签页中具有指定 ID 的 `NamedRange`，或者，对于绑定到文档的脚本，获取活动标签页中具有指定 ID 的 `NamedRange`。
`getNamedRanges()`	`NamedRange[]`	获取第一个标签页中的所有 `NamedRange` 对象，或者对于绑定到文档的脚本，获取活动标签页中的所有 `NamedRange` 对象。
`getNamedRanges(name)`	`NamedRange[]`	获取第一个标签页中或（对于绑定到文档的脚本）活动标签页中具有指定名称的所有 `NamedRange` 对象。
`getSelection()`	`Range\|null`	获取活跃标签页中用户的选择。
`getSupportedLanguageCodes()`	`String[]`	获取 Google 文档文件中支持的所有语言代码。
`getTab(tabId)`	`Tab`	获取具有指定 ID 的 `Tab`。
`getTabs()`	`Tab[]`	获取文档中所有未嵌套的 `Tab`。
`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`。
`setActiveTab(tabId)`	`void`	将当前文档中用户选择的 `Tab` 设置为具有指定 ID 的标签页。
`setCursor(position)`	`Document`	根据 `Position` 设置用户的光标。
`setLanguage(languageCode)`	`Document`	设置文档的语言代码。
`setName(name)`	`Document`	设置文档标题。
`setSelection(range)`	`Document`	根据给定的 `Range` 设置活跃标签页中的用户选择。

详细文档

`addBookmark(position)`

在给定 Position 处向第一个标签页添加 Bookmark，或者，对于绑定到文档的脚本，向活动标签页添加 Bookmark。如需向任何标签页添加书签，请使用 DocumentTab.addBookmark(position) 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the active or first tab's body and adds a paragraph.
const paragraph = doc.getBody().appendParagraph('My new paragraph.');

// Creates a position at the first character of the paragraph text.
const position = doc.newPosition(paragraph.getChild(0), 0);

// Adds a bookmark at the first character of the paragraph text.
const bookmark = doc.addBookmark(position);

// Logs the bookmark ID to the console.
console.log(bookmark.getId());

参数

名称	类型	说明
`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()`

如果第一个标签页（或对于绑定到文档的脚本，则为活动标签页）中不存在页脚部分，则添加一个。如需向任何标签页添加页脚部分，请使用 DocumentTab.addFooter() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Adds a footer to the document's active or first tab.
const footer = doc.addFooter();

// Sets the footer text to 'This is a footer.'
footer.setText('This is a footer');

FooterSection - 标签页页脚。

授权

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

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

`addHeader()`

如果第一个标签页（或对于绑定到文档的脚本，则为活动标签页）中不存在标题部分，则添加一个。如需向任何标签页添加标题部分，请使用 DocumentTab.addHeader() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Adds a header to the document's active or first tab.
const header = doc.addHeader();

// Sets the header text to 'This is a header.'
header.setText('This is a header');

HeaderSection - 标签页标题。

授权

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

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

`addNamedRange(name, range)`

在第一个标签页中添加 NamedRange，即具有名称和 ID 的 Range，以供日后检索；对于绑定到文档的脚本，则在活动标签页中添加 NamedRange。如需在任何标签页中添加 NamedRange，请使用 DocumentTab.addNamedRange(name, range) 方法。名称不一定唯一；同一文档中的多个不同范围可以共享同一名称，这与 HTML 中的类非常相似。相比之下，ID 在文档中是唯一的，就像 HTML 中的 ID 一样。向文档添加NamedRange后，您无法修改该NamedRange，只能将其移除。

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

// Creates a named range that includes every table in the active tab.
const doc = DocumentApp.getActiveDocument();
const rangeBuilder = doc.newRange();
const tables = doc.getBody().getTables();
for (let i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
// Adds the named range to the document's active tab.
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

`getActiveTab()`

获取文档中用户当前有效的 Tab。脚本只能访问运行该脚本的用户的活动标签页，并且只有当脚本绑定到文档时才能访问。

// Display a dialog box that shows the title of the tab that the
// user is currently viewing.
const tab = DocumentApp.getActiveDocument().getActiveTab();
DocumentApp.getUi().alert(`ID of selected tab: ${tab.getTitle()}`);

Tab - 用户的当前有效 Tab，如果脚本未绑定到文档，则为 null。

授权

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

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

`getAs(contentType)`

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

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the document as a PDF.
const pdf = doc.getAs('application/pdf');

// Logs the name of the PDF to the console.
console.log(pdf.getName());

参数

名称	类型	说明
`contentType`	`String`	要转换成的 MIME 类型；支持 `'application/pdf'` 和 `'text/markdown'`。

Blob - 当前文档（以 blob 形式）。

`getBlob()`

以 blob 形式检索当前的 Document 内容。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Retrieves the current document's contents as a blob and logs it to the
// console.
console.log(doc.getBlob().getContentType());

Blob - 当前文档（以 blob 形式）。

`getBody()`

检索第一个标签页的 Body；对于绑定到文档的脚本，则检索活动标签页的 DocumentBodySection。如需获取任何标签页的 DocumentBodySection，请使用 DocumentTab.getBody() 方法。

标签页可能包含不同类型的版块（例如 HeaderSection、FooterSection）。标签页的有效版块为 Body。

Document 中的元素方法委托给有效的 Body。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the active or first tab's body.
const body = doc.getBody();

// Gets the body text and logs it to the console.
console.log(body.getText());

Body - 标签页正文部分。

授权

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

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

`getBookmark(id)`

获取第一个标签页中具有指定 ID 的 Bookmark，或者，对于绑定到文档的脚本，获取活动标签页中具有指定 ID 的 Bookmark。如需获取任何标签页中的书签，请使用 DocumentTab.getBookmark(id) 方法。如果相应 Bookmark 不存在于相应标签页中，此方法会返回 null。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the bookmark by its ID in the document's active or first tab.
const bookmark = doc.getBookmark('id.xyz654321');

// If the bookmark exists, logs the character offset of its position to the
// console. otherwise, logs 'No bookmark exists with the given ID.' to the
// console.
if (bookmark) {
  console.log(bookmark.getPosition().getOffset());
} else {
  console.log('No bookmark exists with the given ID.');
}

参数

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

Bookmark|null - 具有指定 ID 的 Bookmark；如果标签页中不存在此类 Bookmark，则返回 null。

授权

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

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

`getBookmarks()`

获取第一个标签页中的所有 Bookmark 对象，或者对于绑定到文档的脚本，获取活动标签页中的所有 Bookmark 对象。如需获取任何标签页中的所有书签，请使用 DocumentTab.getBookmarks() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
const doc = DocumentApp.openById('123abc');

// Gets all of the bookmarks in the document's active or first tab.
const bookmarks = doc.getBookmarks();

// Logs the number of bookmarks in the tab to the console.
console.log(bookmarks.length);

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.
const 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.
  const 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 - 用户光标的表示形式；如果用户未在标签页中放置光标，或者脚本未绑定到文档，则为 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()`

检索第一个标签页的页脚部分；对于绑定到文档的脚本，则检索活动标签页的页脚部分。如需获取任何标签页的页脚部分，请使用 DocumentTab.getFooter() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the text of the active or first tab's footer and logs it to the console.
console.log(doc.getFooter().getText());

FooterSection|null - 标签页的页脚。

授权

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

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

`getFootnotes()`

检索第一个标签页正文中的所有 Footnote 元素；对于绑定到文档的脚本，则检索活动标签页正文中的所有 Footnote 元素。如需获取任何标签页中的所有脚注，请使用 DocumentTab.getFootnotes() 方法。

对 getFootnotes 的调用会导致对标签页的元素进行迭代。对于大型标签页，请避免不必要地调用此方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the first footnote in the active or first tab's body.
const footnote = doc.getFootnotes()[0];

// Logs footnote contents to the console.
console.log(footnote.getFootnoteContents().getText());

Footnote[]|null - 标签页的脚注。

授权

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

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

`getHeader()`

检索第一个标签页的标题部分；对于绑定到文档的脚本，则检索活动标签页的标题部分。如需获取任何标签页的标题部分，请使用 DocumentTab.getHeader() 方法。

// Opens the Docs file by its ID. If you created your script from within
// a Google Docs file, you can use DocumentApp.getActiveDocument() instead.
// TODO(developer): Replace the ID with your own.
const doc = DocumentApp.openById('123abc');

// Gets the text of the active or first tab's header and logs it to the console.
console.log(doc.getHeader().getText());

HeaderSection|null - 标签页的标题。

授权

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

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，或者，对于绑定到文档的脚本，获取活动标签页中具有指定 ID 的 NamedRange。如需获取任意标签页中具有指定 ID 的 NamedRange，请使用 DocumentTab.getNamedRangeById(id) 方法。如果相应标签页中不存在此类 NamedRange，此方法会返回 null。名称不一定唯一，即使在不同标签页中也是如此；同一标签页中的多个不同范围可以共用同一名称，这与 HTML 中的类非常相似。相比之下，ID 在标签页中是唯一的，就像 HTML 中的 ID 一样。

参数

名称	类型	说明
`id`	`String`	范围的 ID，在相应标签页中具有唯一性。

NamedRange|null - 具有指定 ID 的 NamedRange；如果相应标签页中不存在此类范围，则返回 null。

授权

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

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

`getNamedRanges()`

获取第一个标签页中的所有 NamedRange 对象，或者对于绑定到文档的脚本，获取活动标签页中的所有 NamedRange 对象。如需获取任何标签页中的所有 NamedRange 对象，请使用 DocumentTab.getNamedRanges() 方法。

任何访问相应标签页的脚本都可以访问 NamedRange。为避免脚本之间发生意外冲突，请考虑为范围名称添加唯一字符串作为前缀。

NamedRange[] - 工作表中的 NamedRange 对象数组，可能包含多个同名范围。

授权

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

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

`getNamedRanges(name)`

获取第一个标签页中或（对于绑定到文档的脚本）活动标签页中具有指定名称的所有 NamedRange 对象。如需获取任何标签页中的所有 NamedRange 对象，请使用 DocumentTab.getNamedRanges(name) 方法。名称不一定唯一，即使在不同标签页中也是如此；同一标签页中的多个不同范围可以共用同一名称，这与 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.
const selection = DocumentApp.getActiveDocument().getSelection();
if (selection) {
  const elements = selection.getRangeElements();
  DocumentApp.getUi().alert(`Number of selected elements: ${elements.length}`);
} else {
  DocumentApp.getUi().alert('Nothing is selected.');
}

Range|null - 用户选择的表示形式；如果用户未在标签页中选择任何内容、仅选择了段落末尾、仅选择了段落末尾和换行符，或者脚本未绑定到文档，则为 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

`getTab(tabId)`

获取具有指定 ID 的 Tab。如果不存在此类 Tab，此方法会返回 null。可以访问任何嵌套级别的标签页。

参数

名称	类型	说明
`tabId`	`String`	要获取的标签页的 ID。

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

授权

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

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

`getTabs()`

获取属于文档的所有非嵌套 Tab。

标签页可以包含子标签页，即嵌套在另一个标签页中的标签页。可以使用 Tab.getChildTabs() 访问子标签页。

Tab[] - 文档中所有 Tab 的列表。

授权

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

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

`getUrl()`

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

const 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，请使用 DocumentTab.newPosition(element, offset) 方法。用户的光标以 Position 表示，还有其他用途。

// Append a paragraph to the active tab, then place the user's cursor after the
// first word of the new paragraph.
const doc = DocumentApp.getActiveDocument();
const paragraph = doc.getBody().appendParagraph('My new paragraph.');
const 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 对象。如需创建用于从任何标签页中的标签页元素构建 DocumentRange 对象的构建器，请使用 DocumentTab.newRange() 方法。

// Change the user's selection to a range that includes every table in the
// active tab.
const doc = DocumentApp.getActiveDocument();
const rangeBuilder = doc.newRange();
const tables = doc.getBody().getTables();
for (let 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

`setActiveTab(tabId)`

将当前文档中用户选择的 Tab 设置为具有指定 ID 的标签页。

const doc = DocumentApp.getActiveDocument();

// Sets the user's selected tab by its ID.
// TODO(developer): Replace the ID with your own.
const tab = doc.setActiveTab('123abc');

参数

名称	类型	说明
`tabId`	`String`	要设为有效状态的标签页的 ID。

授权

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

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

`setCursor(position)`

根据 Position 设置用户的光标。脚本只能访问运行该脚本的用户的光标，并且只有当脚本绑定到文档时才能访问。

从不活跃的 Tab 提供 Position 会切换用户的活跃标签页。

const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();

// Append a paragraph, then place the user's cursor after the first word of the
// new paragraph.
const paragraph = documentTab.getBody().appendParagraph('My new paragraph.');
const position = documentTab.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 设置活跃标签页中的用户选择。脚本只能访问正在运行该脚本的用户的选择内容，并且只有当脚本绑定到文档时才能访问。

const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();

// Change the user's selection to a range that includes every table in the
// document.
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let 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

Class Document 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

方法

详细文档

addBookmark(position)

参数

返回

授权

addEditor(emailAddress)

参数

返回

授权

addEditor(user)

参数

返回

授权

addEditors(emailAddresses)

参数

返回

授权

addFooter()

返回

授权

addHeader()

返回

授权

addNamedRange(name, range)

参数

返回

授权

addViewer(emailAddress)

参数

返回

授权

addViewer(user)

参数

返回

授权

addViewers(emailAddresses)

参数

返回

授权

getActiveTab()

返回

授权

getAs(contentType)

参数

返回

getBlob()

返回

getBody()

返回

授权

getBookmark(id)

参数

返回

授权

getBookmarks()

返回

授权

getCursor()

返回

授权

getEditors()

返回

授权

getFooter()

返回

授权

getFootnotes()

返回

授权

getHeader()

返回

授权

getId()

返回

授权

getLanguage()

返回

授权

Class Document

`addBookmark(position)`

`addEditor(emailAddress)`

`addEditor(user)`

`addEditors(emailAddresses)`

`addFooter()`

`addHeader()`

`addNamedRange(name, range)`

`addViewer(emailAddress)`

`addViewer(user)`

`addViewers(emailAddresses)`

`getActiveTab()`

`getAs(contentType)`

`getBlob()`

`getBody()`

`getBookmark(id)`

`getBookmarks()`

`getCursor()`

`getEditors()`

`getFooter()`

`getFootnotes()`

`getHeader()`

`getId()`

`getLanguage()`

`getName()`

`getNamedRangeById(id)`

`getNamedRanges()`

`getNamedRanges(name)`

`getSelection()`

`getSupportedLanguageCodes()`

`getTab(tabId)`

`getTabs()`

`getUrl()`

`getViewers()`

`newPosition(element, offset)`

`newRange()`

`removeEditor(emailAddress)`

`removeEditor(user)`

`removeViewer(emailAddress)`

`removeViewer(user)`

`saveAndClose()`

`setActiveTab(tabId)`

`setCursor(position)`

`setLanguage(languageCode)`

`setName(name)`