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)DocumentDocument 的编辑器列表中移除给定用户。
removeEditor(user)DocumentDocument 的编辑器列表中移除给定用户。
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

参数

名称类型说明
positionPosition新书签的位置

返回

Bookmark - 新书签

授权

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

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

addEditor(emailAddress)

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

参数

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

返回

Document - 此 Document,用于串联。

授权

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

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

addEditor(user)

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

参数

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

返回

Document - 此 Document,用于串联。

授权

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

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

addEditors(emailAddresses)

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

参数

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

返回

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

参数

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

返回

NamedRange - NamedRange

授权

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

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

addViewer(emailAddress)

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

参数

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

返回

Document - 此 Document,用于串联。

授权

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

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

addViewer(user)

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

参数

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

返回

Document - 此 Document,用于串联。

授权

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

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

addViewers(emailAddresses)

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

参数

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

返回

Document - 此 Document,用于串联。

授权

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

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

getAs(contentType)

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

参数

名称类型说明
contentTypeString要转换为的 MIME 类型;目前仅支持 'application/pdf'

返回

Blob - 当前文档作为 blob


getBlob()

将当前 Document 内容检索为 blob。

返回

Blob - 当前文档作为 blob


getBody()

检索活跃文档的 Body

文档可能包含不同类型的部分(例如 HeaderSectionFooterSection)。文档的有效部分是 Body

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

返回

Body - 活跃文档正文部分

授权

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

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

getBookmark(id)

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

参数

名称类型说明
idStringBookmark的 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 一样。

参数

名称类型说明
idString范围的 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 可供访问文档的任何脚本访问。为避免脚本之间发生意外冲突,不妨考虑使用唯一字符串作为范围名称的前缀。

参数

名称类型说明
nameString范围的名称,该名称不必是唯一的

返回

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

参数

名称类型说明
elementElement包含新 Position 的元素;这必须是 Text 元素或 Paragraph 之类的容器元素
offsetInteger对于 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

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

参数

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

返回

Document - 此 Document,用于串联。

授权

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

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

removeEditor(user)

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

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

参数

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

返回

Document - 此 Document,用于串联。

授权

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

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

removeViewer(emailAddress)

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

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

参数

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

返回

Document - 用于串联的 Document

授权

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

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

removeViewer(user)

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

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

参数

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

返回

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

参数

名称类型说明
positionPosition新的光标位置

返回

Document - 此 Document,用于连锁

授权

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

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

setLanguage(languageCode)

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

参数

名称类型说明
languageCodeString语言代码。

返回

Document - 此 Document,用于串联。

授权

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

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

setName(name)

设置文档标题。

参数

名称类型说明
nameString新文档标题

返回

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

参数

名称类型说明
rangeRange新选择的元素范围

返回

Document - 此 Document,用于连锁

授权

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

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