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以 blob 形式检索当前 Document 内容。
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)DocumentDocument 的查看者和评论者列表中删除指定用户。
removeViewer(user)DocumentDocument 的查看者和评论者列表中删除指定用户。
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。为避免脚本之间发生意外冲突,请考虑在范围名称前添加一个唯一字符串作为前缀。

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

参数

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

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

返回

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 - 表示用户的选择,如果用户未在文档中选择任何内容,则仅选择段落结尾、仅选择段落结尾和新行,或者脚本未绑定到文档。

授权

使用此方法的脚本需要通过以下一个或多个范围进行授权:

  • 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