此页面由 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`，以供日后检索。
`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`	获取第一个标签页或活动标签页（对于绑定到文档的脚本）中具有给定 ID 的 `Bookmark`。
`getBookmarks()`	`Bookmark[]`	获取第一个标签页中的所有 `Bookmark` 对象，对于绑定到文档的脚本，则获取活动标签页中的所有 `Bookmark` 对象。
`getCursor()`	`Position`	获取用户在当前标签页中的光标。
`getEditors()`	`User[]`	获取此 `Document` 的编辑器列表。
`getFooter()`	`FooterSection`	检索第一个标签页的页脚部分，对于绑定到文档的脚本，则检索活动标签页的页脚部分。
`getFootnotes()`	`Footnote[]`	检索第一个标签页正文中的所有 `Footnote` 元素，或者对于绑定到文档的脚本，则检索活动标签页的正文中的所有 `Footnote` 元素。
`getHeader()`	`HeaderSection`	检索第一个标签页的标题部分，对于绑定到文档的脚本，则检索活动标签页的标题部分。
`getId()`	`String`	检索文档的唯一标识符。
`getLanguage()`	`String`	获取文档的语言代码。
`getName()`	`String`	检索文档的标题。
`getNamedRangeById(id)`	`NamedRange`	获取第一个标签页或活动标签页（对于绑定到文档的脚本）中具有给定 ID 的 `NamedRange`。
`getNamedRanges()`	`NamedRange[]`	获取第一个标签页中的所有 `NamedRange` 对象，对于绑定到文档的脚本，则获取活动标签页中的所有 `NamedRange` 对象。
`getNamedRanges(name)`	`NamedRange[]`	获取第一个标签页（对于绑定到文档的脚本，则为当前标签页）中具有给定名称的所有 `NamedRange` 对象。
`getSelection()`	`Range`	获取用户在“活跃”标签页中的选择。
`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，对于绑定到文档的脚本，则添加到活动标签页。如需向任何标签页添加书签，请使用 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，请使用 DocumentTab.addNamedRange(name, range) 方法。名称不一定是唯一的；同一文档中的多个不同范围可以共用相同的名称，就像 HTML 中的类一样。与之相反，ID 在文档中是唯一的，就像 HTML 中的 ID 一样。向文档添加 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。如需获取任何标签页中的书签，请使用 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 - 具有给定 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。

授权

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

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 - 标签页的页脚。

授权

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

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[] - 标签页的脚注。

授权

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

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 - 标签页的标题。

授权

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

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()`

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

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，请使用 DocumentTab.getNamedRangeById(id) 方法。如果标签页中不存在此类 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 对象，请使用 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。

授权

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

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)`

设置文档的语言代码。这是文档编辑器的 File（文件）> Language（语言） 中显示的语言，可能不是文档实际使用的语言。使用 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